devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/llm/provider.py

@@ -1,34 +1,162 @@
 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
+from pydantic import BaseModel, field_validator
 import httpx
 import json
 from pathlib import Path
+import yaml
 
-SUPPORTED_MODEL_PROVIDERS = ("openrouter",)
+logger = logging.getLogger(__name__)
+
+SUPPORTED_MODEL_PROVIDERS = ("openrouter", "vertexai", "doubleword", "ollama")
+PROVIDER_ALIASES = {
+    "vertex-ai": "vertexai",
+    "vertex_ai": "vertexai",
+    "ollama-local": "ollama",
+    "ollama_local": "ollama",
+}
+MODEL_DEFAULTS_RESOURCE = "model_defaults.yaml"
+
+
+@lru_cache(maxsize=1)
+def load_default_role_models_by_provider() -> Dict[str, Dict[str, str]]:
+    data = resources.files(__package__).joinpath(MODEL_DEFAULTS_RESOURCE).read_text(encoding="utf-8")
+    loaded = yaml.safe_load(data) or {}
+    return {
+        str(provider): {str(role): str(model) for role, model in roles.items()}
+        for provider, roles in loaded.items()
+        if isinstance(roles, dict)
+    }
+
+
+DEFAULT_ROLE_MODELS_BY_PROVIDER = load_default_role_models_by_provider()
+
+
+class ProviderRequestError(RuntimeError):
+    """A provider HTTP request failed, with an actionable, user-facing message."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def raise_for_provider_status(response: "httpx.Response", provider: str) -> None:
+    """Translate an HTTP error response into an actionable ProviderRequestError.
+
+    The raw ``httpx.HTTPStatusError`` surfaces as an unhelpful traceback; common
+    statuses (auth, billing, rate limiting) have concrete remedies worth naming.
+    """
+    status = getattr(response, "status_code", None)
+    if status is None or status < 400:
+        return
+    hints = {
+        401: "authentication failed — check the API key in .devcouncil/secrets.env",
+        402: "payment required — the account is out of credits or has no active balance; add funds and retry",
+        403: "access forbidden — the API key may lack access to the requested model",
+        404: "not found — check the configured model id and provider base URL",
+        429: "rate limited — too many requests; wait a moment and retry",
+    }
+    detail = hints.get(status, "the request was rejected")
+    body = ""
+    text = getattr(response, "text", None)
+    if isinstance(text, str):
+        body = text.strip()[:300]
+    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)
 
 
 class LLMResponse(BaseModel):
     content: str
     model: str
-    usage: Dict[str, int]
+    # OpenRouter (and other providers) return richer usage payloads than plain
+    # token counts: a float ``cost`` plus nested ``*_details`` dicts. Keep this
+    # permissive so live responses parse; downstream only reads the int token keys.
+    usage: Dict[str, Any]
     raw_response: Dict[str, Any]
 
+    @field_validator("content", mode="before")
+    @classmethod
+    def _coerce_null_content(cls, value: Any) -> str:
+        # Providers return ``content: null`` for reasoning-only, tool-only, or
+        # filtered responses. Treat that as empty text so the router's parse /
+        # healing path can retry instead of crashing on a validation error.
+        return value if value is not None else ""
+
 class Provider(ABC):
     @abstractmethod
     async def complete(
-        self, 
-        model: str, 
-        messages: List[Dict[str, str]], 
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
         temperature: float = 0.0,
-        json_mode: bool = False
+        json_mode: bool = False,
+        task_id: Optional[str] = None,
+        run_id: Optional[str] = None,
     ) -> 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
+        ``(model, messages, temperature, json_mode)``; overridden where a runtime knob
+        (e.g. Ollama's ``num_ctx`` / base URL) silently alters results for an identical
+        prompt."""
+        return ""
+
+    def is_local_cost_free(self) -> bool:
+        """True for on-device providers that incur no per-token cost (Ollama). Lets the
+        telemetry tracker zero local usage by PROVIDER rather than by model-id matching —
+        local model tags are open-ended (``qwen2.5-coder:7b``) and may collide with priced
+        entries. Mirrors the provider-based zeroing in ``telemetry/cost.py``."""
+        return False
+
 
 def validate_model_provider(provider_name: str) -> str:
     normalized = provider_name.strip().lower()
+    normalized = PROVIDER_ALIASES.get(normalized, normalized)
     if normalized in SUPPORTED_MODEL_PROVIDERS:
         return normalized
     supported = ", ".join(SUPPORTED_MODEL_PROVIDERS)
@@ -38,26 +166,173 @@ def validate_model_provider(provider_name: str) -> str:
     )
 
 
-def create_provider(provider_name: str, api_key: str) -> Provider:
+def apply_provider_default_role_models(
+    raw_config: Dict[str, Any],
+    previous_provider: str,
+    new_provider: str,
+) -> bool:
+    """Update role defaults when switching providers without overwriting custom models."""
+    new = validate_model_provider(new_provider)
+    models = raw_config.setdefault("models", {})
+    roles = models.setdefault("roles", {})
+    try:
+        previous = validate_model_provider(previous_provider)
+        previous_defaults = DEFAULT_ROLE_MODELS_BY_PROVIDER[previous]
+    except ValueError:
+        previous_defaults = {}
+    new_defaults = DEFAULT_ROLE_MODELS_BY_PROVIDER[new]
+    changed = False
+
+    for role, new_model in new_defaults.items():
+        role_config = roles.setdefault(role, {})
+        current_model = role_config.get("model")
+        if current_model is None or current_model == previous_defaults.get(role):
+            if current_model != new_model:
+                role_config["model"] = new_model
+                changed = True
+
+    return changed
+
+
+def build_role_model_config(
+    provider: str = "openrouter",
+    model: str | None = None,
+    role_models: Dict[str, str] | None = None,
+) -> Dict[str, Dict[str, str]]:
+    """Build config-ready model role mappings for a provider.
+
+    If ``model`` is supplied, it is used for every known role. Per-role entries
+    in ``role_models`` override both provider defaults and the shared model.
+    """
+    normalized = validate_model_provider(provider)
+    roles = {
+        role: {"model": selected_model}
+        for role, selected_model in DEFAULT_ROLE_MODELS_BY_PROVIDER[normalized].items()
+    }
+    if model:
+        roles = {role: {"model": model} for role in roles}
+    for role, selected_model in (role_models or {}).items():
+        roles[role] = {"model": selected_model}
+    return roles
+
+
+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)
+        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":
+        return OllamaProvider(api_key, project_root=project_root)
+    if normalized == "vertexai":
+        from devcouncil.app.config import load_local_secrets
+        local_secrets = load_local_secrets(project_root)
+        project_id = (
+            os.environ.get("VERTEXAI_PROJECT")
+            or os.environ.get("GOOGLE_CLOUD_PROJECT")
+            or local_secrets.get("VERTEXAI_PROJECT")
+            or local_secrets.get("GOOGLE_CLOUD_PROJECT")
+        )
+        location = os.environ.get("VERTEXAI_LOCATION") or local_secrets.get("VERTEXAI_LOCATION", "global")
+        return VertexAIProvider(api_key, project_id=project_id, location=location, project_root=project_root)
     raise AssertionError(f"Provider validation passed for unhandled provider: {normalized}")
 
+
+def _log_model_call(
+    payload: Dict[str, Any],
+    data: Dict[str, Any],
+    usage: Dict[str, int],
+    project_root: Path = Path("."),
+    task_id: Optional[str] = None,
+    run_id: Optional[str] = None,
+    provider: Optional[str] = None,
+) -> None:
+    try:
+        from datetime import datetime, timezone
+
+        from devcouncil.utils.redaction import redact_dict
+        # Resolve against the provider's project root, not the process cwd — otherwise
+        # running `dev` from another directory logged spend to the wrong project.
+        log_dir = project_root / ".devcouncil" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_file = log_dir / "model_calls.jsonl"
+
+        # task_id/run_id/timestamp/provider are optional and backward-compatible: older
+        # records simply lack them and are grouped under "(unattributed)" by the cost
+        # reporter. provider lets the cost ledger zero-cost local providers (ollama)
+        # regardless of the open-ended model tag Ollama echoes back.
+        log_payload = {
+            "request": redact_dict(payload),
+            "response": redact_dict(data),
+            "usage": usage,
+            "task_id": task_id,
+            "run_id": run_id,
+            "provider": provider,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(log_payload) + "\n")
+    except Exception as e:
+        import logging as _log
+        _log.getLogger(__name__).debug("Failed to log model call: %s", e)
+
+
 class OpenRouterProvider(Provider):
-    def __init__(self, api_key: str):
+    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, 
         model: str, 
         messages: List[Dict[str, str]], 
         temperature: float = 0.0,
-        json_mode: bool = False
+        json_mode: bool = False,
+        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}",
@@ -65,55 +340,346 @@ 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:
+        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)
+
+        return resp
+
+
+class DoublewordProvider(Provider):
+    def __init__(self, api_key: str, project_root: Path = Path(".")):
+        self.api_key = api_key
+        self.base_url = "https://api.doubleword.ai/v1"
+        self.project_root = project_root
+
+    async def complete(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.0,
+        json_mode: bool = False,
+        task_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+    ) -> LLMResponse:
+        # 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",
+        }
+        payload = {
+            "model": model,
+            "messages": msgs,
+            "temperature": temperature,
+        }
+
+        if json_mode:
+            payload["response_format"] = {"type": "json_object"}
+            if msgs[-1]["role"] == "user":
+                msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
+
+        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
+
+
+class OllamaProvider(Provider):
+    """Local Ollama provider via its NATIVE ``/api/chat`` endpoint.
+
+    Ollama needs no API key. The base URL is overridable via ``OLLAMA_BASE_URL``
+    (taken verbatim) or Ollama's native ``OLLAMA_HOST`` (normalized: a missing scheme
+    is prefixed with ``http://`` and a missing ``/v1`` suffix is appended). The actual
+    request goes to the native ``/api/chat`` endpoint (derived by stripping a trailing
+    ``/v1``) rather than the OpenAI-compatible ``/v1/chat/completions`` — because the
+    native endpoint is the only one that honors ``options.num_ctx`` (set via
+    ``OLLAMA_NUM_CTX``) and ``format: json``. DevCouncil's planning prompts are large
+    (up to ~15k tokens), so without a raised ``num_ctx`` Ollama's small default context
+    would silently truncate them.
+    """
+
+    def __init__(
+        self,
+        api_key: str = "",
+        project_root: Path = Path("."),
+        base_url: str | None = None,
+        num_ctx: int | None = None,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url or self._resolve_base_url()
+        self.project_root = project_root
+        self.num_ctx = num_ctx if num_ctx is not None else self._resolve_num_ctx()
+        self.timeout = self._resolve_timeout()
+
+    # Local generation latency is unbounded (cold loads, CPU-only hosts, large
+    # ``num_ctx``) and is not a network failure, so Ollama gets a generous default
+    # and an explicit override rather than the cloud providers' fixed 180s.
+    DEFAULT_TIMEOUT = 600.0
+
+    @staticmethod
+    def _resolve_timeout() -> float | None:
+        """Read timeout from ``OLLAMA_TIMEOUT`` seconds (positive float). ``0``/``none``/
+        ``off`` disables it entirely for very slow local models; unset/invalid falls back
+        to :data:`DEFAULT_TIMEOUT`."""
+        raw = os.environ.get("OLLAMA_TIMEOUT")
+        if raw is None:
+            return OllamaProvider.DEFAULT_TIMEOUT
+        raw = raw.strip().lower()
+        if raw in {"0", "none", "off", ""}:
+            return None
+        try:
+            value = float(raw)
+        except ValueError:
+            return OllamaProvider.DEFAULT_TIMEOUT
+        return value if value > 0 else None
+
+    def cache_fingerprint(self) -> str:
+        # num_ctx and the target server change the response for an identical prompt (a
+        # larger window avoids the truncation a smaller one silently applies; a different
+        # endpoint is a different model server), so both must invalidate the cache. Key on
+        # the *normalized* /api/chat endpoint, not the raw base_url, so equivalent configs
+        # (OLLAMA_HOST vs OLLAMA_BASE_URL, with/without a trailing /v1) collapse to one key.
+        return f"ollama:num_ctx={self.num_ctx};endpoint={self._chat_endpoint()}"
+
+    def is_local_cost_free(self) -> bool:
+        return True
+
+    @staticmethod
+    def _resolve_base_url() -> str:
+        explicit = os.environ.get("OLLAMA_BASE_URL")
+        if explicit:
+            return explicit.rstrip("/")
+        host = os.environ.get("OLLAMA_HOST")
+        if host:
+            host = host.strip()
+            if "://" not in host:
+                host = f"http://{host}"
+            host = host.rstrip("/")
+            if not host.endswith("/v1"):
+                host = f"{host}/v1"
+            return host
+        return "http://localhost:11434/v1"
+
+    @staticmethod
+    def _resolve_num_ctx() -> int | None:
+        """Context window from ``OLLAMA_NUM_CTX`` (positive int), else None (server default)."""
+        raw = os.environ.get("OLLAMA_NUM_CTX")
+        if not raw:
+            return None
+        try:
+            value = int(raw)
+        except (TypeError, ValueError):
+            return None
+        return value if value > 0 else None
+
+    def _chat_endpoint(self) -> str:
+        """Native chat endpoint derived from base_url (strip a trailing ``/v1``)."""
+        root = self.base_url.rstrip("/")
+        if root.endswith("/v1"):
+            root = root[: -len("/v1")].rstrip("/")
+        return f"{root}/api/chat"
+
+    async def complete(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.0,
+        json_mode: bool = False,
+        task_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+    ) -> LLMResponse:
+        # 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",
+        }
+        # Ollama ignores auth, but a configured key (e.g. for a reverse proxy)
+        # passes through harmlessly.
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        # Native /api/chat options. temperature and num_ctx live under "options"; a
+        # raised num_ctx (OLLAMA_NUM_CTX) prevents silent truncation of large prompts.
+        options: Dict[str, Any] = {"temperature": temperature}
+        if self.num_ctx:
+            options["num_ctx"] = self.num_ctx
+
+        payload: Dict[str, Any] = {
+            "model": model,
+            "messages": msgs,
+            "stream": False,
+            "options": options,
+        }
+
+        if json_mode:
+            # Native structured-output switch (more reliable than OpenAI response_format
+            # on Ollama). Still nudge the prompt so the model knows to emit JSON.
+            payload["format"] = "json"
+            if msgs[-1]["role"] == "user":
+                msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
+
+        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
+
+
+class VertexAIProvider(Provider):
+    """Vertex AI provider using Google's OpenAI-compatible Chat Completions API."""
+
+    def __init__(self, access_token: str, project_id: str | None = None, location: str | None = None, project_root: Path = Path(".")):
+        self.access_token = access_token
+        self.project_id = project_id or os.environ.get("VERTEXAI_PROJECT") or os.environ.get("GOOGLE_CLOUD_PROJECT")
+        self.location = location or os.environ.get("VERTEXAI_LOCATION", "global")
+        self.project_root = project_root
+
+    @property
+    def base_url(self) -> str:
+        if not self.project_id:
+            raise ValueError(
+                "Vertex AI project is not configured. Set VERTEXAI_PROJECT or GOOGLE_CLOUD_PROJECT."
+            )
+        return (
+            f"https://aiplatform.googleapis.com/v1/projects/{self.project_id}"
+            f"/locations/{self.location}/endpoints/openapi"
+        )
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+    def _refresh_access_token_from_gcloud(self) -> bool:
+        from devcouncil.app.config import get_gcloud_access_token
+
+        refreshed = get_gcloud_access_token()
+        if not refreshed:
+            return False
+        self.access_token = refreshed
+        return True
+
+    async def complete(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.0,
+        json_mode: bool = False,
+        task_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+    ) -> LLMResponse:
+        # 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,
+            "messages": msgs,
+            "temperature": temperature,
+        }
+
+        if json_mode:
+            payload["response_format"] = {"type": "json_object"}
+            if msgs[-1]["role"] == "user":
+                msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
+
+        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=headers,
-                json=payload
-            )
-            response.raise_for_status()
-            data = response.json()
-            
-            resp = LLMResponse(
-                content=data["choices"][0]["message"]["content"],
-                model=data["model"],
-                usage=data.get("usage", {}),
-                raw_response=data
+                headers=self._headers(),
+                json=payload,
             )
-            
-            # Log the call
-            try:
-                from devcouncil.utils.redaction import redact_dict
-                log_dir = Path(".devcouncil/logs")
-                log_dir.mkdir(parents=True, exist_ok=True)
-                log_file = log_dir / "model_calls.jsonl"
-                
-                # Create a redacted copy of both request and response for logging
-                log_payload = {
-                    "request": redact_dict(payload),
-                    "response": redact_dict(data),
-                    "usage": resp.usage,
-                }
-                with open(log_file, "a", encoding="utf-8") as f:
-                    f.write(json.dumps(log_payload) + "\n")
-            except Exception as e:
-                import logging as _log
-                _log.getLogger(__name__).debug("Failed to log model call: %s", e)
-                
-            return resp
+        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
 
 class MockProvider(Provider):
     """Mock provider for dry runs and testing."""
@@ -127,7 +693,9 @@ class MockProvider(Provider):
         model: str, 
         messages: List[Dict[str, str]], 
         temperature: float = 0.0,
-        json_mode: bool = False
+        json_mode: bool = False,
+        task_id: Optional[str] = None,
+        run_id: Optional[str] = None,
     ) -> LLMResponse:
         res = self.responses.get(model, '{"mock": "response"}')