devcouncil 0.1.1 → 0.2.0

package/src/devcouncil/llm/provider.py

@@ -1,34 +1,123 @@
 from abc import ABC, abstractmethod
 import copy
+from functools import lru_cache
+from importlib import resources
+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",)
+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}"
+    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 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,23 +127,131 @@ 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 create_provider(provider_name: str, api_key: str, project_root: Path = Path(".")) -> Provider:
     normalized = validate_model_provider(provider_name)
     if normalized == "openrouter":
-        return OpenRouterProvider(api_key)
+        return OpenRouterProvider(api_key, project_root=project_root)
+    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(".")):
         self.api_key = api_key
         self.base_url = "https://openrouter.ai/api/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
+        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)
@@ -84,35 +281,317 @@ class OpenRouterProvider(Provider):
                 headers=headers,
                 json=payload
             )
-            response.raise_for_status()
+            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 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)
-                
+
+            _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:
+        msgs = copy.deepcopy(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."
+
+        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
+            )
+
+            _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:
+        msgs = copy.deepcopy(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."
+
+        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,
+            )
+
+            _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:
+        msgs = copy.deepcopy(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."
+
+        async with httpx.AsyncClient(timeout=180.0) as client:
+            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
+            )
+
+            _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
             return resp
 
 class MockProvider(Provider):
@@ -127,7 +606,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"}')