feat(cp4): port cloud providers (openai/anthropic/gemini/ollama) into proteus

proteus/providers/anthropic_provider.py

@@ -0,0 +1,198 @@
+"""Anthropic provider for Claude-family models.
+
+Uses the official anthropic Python client (sync) to call the messages API.
+Handles the Anthropic-specific system message placement and thinking content
+blocks.
+
+Example configuration::
+
+    provider:
+      type: anthropic
+      model: claude-sonnet-4-20250514
+      # api_key: defaults to ANTHROPIC_API_KEY env var
+
+Note: This file is intentionally named ``anthropic_provider.py`` (not
+``anthropic.py``) to avoid shadowing the ``anthropic`` package.
+"""
+
+import logging
+import os
+import time
+
+from anthropic import Anthropic
+from anthropic import APIError, APITimeoutError, RateLimitError
+
+from proteus.providers.base import CompletionResult, LLMProvider
+
+logger = logging.getLogger(__name__)
+
+_RETRYABLE_EXCEPTIONS = (RateLimitError, APITimeoutError, APIError)
+_MAX_RETRIES = 3
+_BACKOFF_SECONDS = (1, 2, 4)
+
+
+class AnthropicProvider(LLMProvider):
+    """LLM provider backed by the Anthropic messages API.
+
+    Args:
+        model: Model identifier (e.g. ``"claude-sonnet-4-20250514"``).
+        api_key: Anthropic API key. Falls back to ``ANTHROPIC_API_KEY`` env var.
+        base_url: Custom API base URL for private Anthropic deployments.
+        max_retries: Number of retries on transient failures.
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        model: str = "claude-sonnet-4-20250514",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int = 3,
+        timeout: float = 120.0,
+        top_p: float = 0.0,
+        top_k: int = 0,
+        enable_thinking: bool | None = None,
+        thinking_budget: int | None = None,
+    ) -> None:
+        self._model = model
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._top_p = top_p
+        self._top_k = top_k
+        self._enable_thinking = enable_thinking
+        self._thinking_budget = thinking_budget
+        resolved_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Anthropic API key must be provided via api_key param "
+                "or ANTHROPIC_API_KEY environment variable."
+            )
+        client_kwargs: dict = {"api_key": resolved_key}
+        if base_url:
+            client_kwargs["base_url"] = base_url
+        self._client = Anthropic(**client_kwargs)
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    def complete(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+    ) -> CompletionResult:
+        """Send a messages request with retry on transient failures.
+
+        System messages are extracted from ``messages`` and passed via the
+        dedicated ``system`` parameter, as required by the Anthropic API.
+
+        Args:
+            messages: Chat messages with ``role`` and ``content`` keys.
+                Messages with ``role="system"`` are extracted automatically.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate.
+
+        Returns:
+            CompletionResult containing response text and token usage.
+
+        Raises:
+            anthropic.APIError: After exhausting all retries.
+        """
+        system_text, non_system = self._split_system_messages(messages)
+
+        kwargs: dict = {
+            "model": self._model,
+            "messages": non_system,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if self._top_p > 0.0:
+            kwargs["top_p"] = self._top_p
+        if self._top_k > 0:
+            kwargs["top_k"] = self._top_k
+        if system_text:
+            kwargs["system"] = system_text
+
+        # Extended thinking support (Claude 3.5+).
+        # Anthropic requires temperature=1.0 when thinking is enabled.
+        if self._enable_thinking:
+            budget = self._thinking_budget or 10240
+            kwargs["thinking"] = {
+                "type": "enabled",
+                "budget_tokens": budget,
+            }
+            kwargs["temperature"] = 1.0
+
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.messages.create(**kwargs)
+                break
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_error = exc
+                if attempt < self._max_retries:
+                    wait = _BACKOFF_SECONDS[min(attempt, len(_BACKOFF_SECONDS) - 1)]
+                    logger.warning(
+                        "Anthropic request failed (attempt %d/%d): %s. "
+                        "Retrying in %ds...",
+                        attempt + 1,
+                        self._max_retries + 1,
+                        exc,
+                        wait,
+                    )
+                    time.sleep(wait)
+        else:
+            raise last_error  # type: ignore[misc]
+
+        # Extract text and thinking tokens from content blocks.
+        text_parts: list[str] = []
+        thinking_text_parts: list[str] = []
+        thinking_tokens = 0
+        for block in response.content:
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type == "thinking":
+                thinking_tokens += getattr(
+                    block, "input_tokens", len(block.thinking) // 4
+                )
+                thinking_text_parts.append(block.thinking)
+
+        text = "\n".join(text_parts)
+        thinking_text = "\n".join(thinking_text_parts) if thinking_text_parts else None
+
+        usage = response.usage
+        input_tokens = usage.input_tokens
+        output_tokens = usage.output_tokens
+        finish_reason = response.stop_reason  # "end_turn", "max_tokens", etc.
+
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            thinking_tokens=thinking_tokens,
+            thinking_text=thinking_text,
+            finish_reason=finish_reason,
+        )
+
+    @staticmethod
+    def _split_system_messages(
+        messages: list[dict[str, str]],
+    ) -> tuple[str, list[dict[str, str]]]:
+        """Separate system messages from user/assistant messages.
+
+        The Anthropic API requires the system prompt to be passed as a
+        top-level ``system`` parameter rather than as a message with
+        ``role="system"``.
+
+        Returns:
+            A tuple of (concatenated system text, remaining messages).
+        """
+        system_parts: list[str] = []
+        non_system: list[dict[str, str]] = []
+        for msg in messages:
+            if msg["role"] == "system":
+                system_parts.append(msg["content"])
+            else:
+                non_system.append(msg)
+        return "\n\n".join(system_parts), non_system

proteus/providers/gemini.py

@@ -0,0 +1,222 @@
+"""Google Gemini provider for Gemini-family models.
+
+Uses the official google-genai Python SDK (sync) to call generate_content.
+Supports thinking tokens from Gemini 2.5+ models for Reasoning Investment
+tracking.
+
+Example configuration::
+
+    provider:
+      type: gemini
+      model: gemini-2.0-flash
+      # api_key: defaults to GEMINI_API_KEY env var
+"""
+
+import logging
+import os
+import time
+
+from google import genai
+from google.genai import types
+from google.genai.errors import APIError, ClientError, ServerError
+
+from proteus.providers.base import CompletionResult, LLMProvider
+
+logger = logging.getLogger(__name__)
+
+_RETRYABLE_EXCEPTIONS = (ServerError, ClientError, APIError)
+_MAX_RETRIES = 3
+_BACKOFF_SECONDS = (2, 4, 8)
+
+
+class GeminiProvider(LLMProvider):
+    """LLM provider backed by the Google Gemini API.
+
+    Args:
+        model: Model identifier (e.g. ``"gemini-2.0-flash"``).
+        api_key: Gemini API key. Falls back to ``GEMINI_API_KEY`` env var.
+        max_retries: Number of retries on transient failures.
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        model: str = "gemini-2.0-flash",
+        api_key: str | None = None,
+        max_retries: int = 3,
+        timeout: float = 120.0,
+        top_p: float = 0.0,
+        top_k: int = 0,
+        seed: int | None = None,
+        enable_thinking: bool | None = None,
+        thinking_budget: int | None = None,
+        reasoning_effort: str | None = None,
+    ) -> None:
+        self._model = model
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._top_p = top_p
+        self._top_k = top_k
+        self._seed = seed
+        self._enable_thinking = enable_thinking
+        self._thinking_budget = thinking_budget
+        self._reasoning_effort = reasoning_effort
+        resolved_key = api_key or os.environ.get("GEMINI_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Gemini API key must be provided via api_key param "
+                "or GEMINI_API_KEY environment variable."
+            )
+        self._client = genai.Client(
+            api_key=resolved_key,
+            http_options=types.HttpOptions(timeout=int(timeout * 1000)),
+        )
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    def complete(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+    ) -> CompletionResult:
+        """Send a generate_content request with retry on transient failures.
+
+        System messages are extracted and passed via the ``system_instruction``
+        parameter, as required by the Gemini API.
+
+        Args:
+            messages: Chat messages with ``role`` and ``content`` keys.
+                Messages with ``role="system"`` are extracted automatically.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens to generate.
+
+        Returns:
+            CompletionResult containing response text and token usage.
+
+        Raises:
+            google.genai.errors.APIError: After exhausting all retries.
+        """
+        system_text, contents = self._convert_messages(messages)
+
+        config_kwargs: dict = {
+            "temperature": temperature,
+            "max_output_tokens": max_tokens,
+        }
+        if self._top_p > 0.0:
+            config_kwargs["top_p"] = self._top_p
+        if self._top_k > 0:
+            config_kwargs["top_k"] = self._top_k
+        if self._seed is not None:
+            config_kwargs["seed"] = self._seed
+
+        # Thinking config: always include thoughts for RI tracking.
+        thinking_kwargs: dict = {"include_thoughts": True}
+        if self._thinking_budget is not None:
+            thinking_kwargs["thinking_budget"] = self._thinking_budget
+        if self._reasoning_effort:
+            thinking_kwargs["thinking_level"] = self._reasoning_effort
+        if self._enable_thinking is False:
+            thinking_kwargs = {"include_thoughts": False}
+
+        config_kwargs["thinking_config"] = types.ThinkingConfig(**thinking_kwargs)
+        config = types.GenerateContentConfig(**config_kwargs)
+        if system_text:
+            config.system_instruction = system_text
+
+        last_error: Exception | None = None
+        response = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.models.generate_content(
+                    model=self._model,
+                    contents=contents,
+                    config=config,
+                )
+                break
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_error = exc
+                if attempt < self._max_retries:
+                    wait = _BACKOFF_SECONDS[min(attempt, len(_BACKOFF_SECONDS) - 1)]
+                    logger.warning(
+                        "Gemini request failed (attempt %d/%d): %s. "
+                        "Retrying in %ds...",
+                        attempt + 1,
+                        self._max_retries + 1,
+                        exc,
+                        wait,
+                    )
+                    time.sleep(wait)
+        else:
+            raise last_error  # type: ignore[misc]
+
+        # Extract text and thinking from response parts.
+        text_parts: list[str] = []
+        thinking_text_parts: list[str] = []
+        finish_reason = None
+        if response.candidates:
+            candidate = response.candidates[0]
+            finish_reason = getattr(candidate, "finish_reason", None)
+            # Gemini returns enum; convert to string.
+            if finish_reason is not None:
+                finish_reason = str(finish_reason).lower()
+            for part in candidate.content.parts:
+                if part.thought:
+                    if part.text:
+                        thinking_text_parts.append(part.text)
+                elif part.text:
+                    text_parts.append(part.text)
+
+        text = "\n".join(text_parts)
+        thinking_text = "\n".join(thinking_text_parts) if thinking_text_parts else None
+
+        # Token counts from usage metadata.
+        usage = response.usage_metadata
+        input_tokens = usage.prompt_token_count or 0 if usage else 0
+        output_tokens = usage.candidates_token_count or 0 if usage else 0
+
+        # Prefer API-reported thinking token count; fall back to heuristic.
+        thinking_tokens = 0
+        if usage and usage.thoughts_token_count:
+            thinking_tokens = usage.thoughts_token_count
+        elif thinking_text_parts:
+            thinking_tokens = len("".join(thinking_text_parts)) // 4
+
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            thinking_tokens=thinking_tokens,
+            thinking_text=thinking_text,
+            finish_reason=finish_reason,
+        )
+
+    @staticmethod
+    def _convert_messages(
+        messages: list[dict[str, str]],
+    ) -> tuple[str, list[types.Content]]:
+        """Convert OpenAI-style messages to Gemini Content objects.
+
+        Separates system messages and maps ``assistant`` role to ``model``.
+
+        Returns:
+            A tuple of (system instruction text, list of Content objects).
+        """
+        system_parts: list[str] = []
+        contents: list[types.Content] = []
+        for msg in messages:
+            role = msg["role"]
+            if role == "system":
+                system_parts.append(msg["content"])
+            else:
+                # Gemini uses "model" instead of "assistant".
+                gemini_role = "model" if role == "assistant" else "user"
+                contents.append(
+                    types.Content(
+                        role=gemini_role,
+                        parts=[types.Part(text=msg["content"])],
+                    )
+                )
+        return "\n\n".join(system_parts), contents

proteus/providers/ollama_cloud.py

@@ -0,0 +1,313 @@
+"""Ollama Cloud provider for Qwen3 / GPT-OSS / DeepSeek reasoning models.
+
+Unlike :class:`LocalProvider` (which targets the OpenAI-compatible
+``/v1/chat/completions`` endpoint and therefore strips the native
+``message.thinking`` field), this provider speaks Ollama's **native**
+``/api/chat`` protocol so that reasoning content is returned as a
+structured ``message.thinking`` string — the shape the Phase O Unit 15
+split-call analyses expect for `thinking_text_task` /
+`thinking_text_forfeit`.
+
+The endpoint, authentication, and payload schema follow the Ollama Cloud
+docs (https://docs.ollama.com/cloud, https://docs.ollama.com/capabilities/thinking):
+
+- Base URL default: ``https://ollama.com``
+- Path: ``POST /api/chat``
+- Auth: ``Authorization: Bearer $OLLAMA_API_KEY``
+- Request body: ``{model, messages, stream=false, think, options{...}}``
+- Response body: ``{message:{content, thinking}, prompt_eval_count,
+  eval_count, done_reason, ...}``
+
+Example configuration::
+
+    provider:
+      provider: ollama_cloud
+      model: qwen3.5:cloud
+      api_key_env: OLLAMA_API_KEY
+      enable_thinking: true
+      temperature: 0.7
+      top_p: 0.95
+      top_k: 20
+
+The ``enable_thinking`` toggle is forwarded to Ollama as ``think``
+(boolean). For ``gpt-oss`` models that require a level
+(``"low"``/``"medium"``/``"high"``), pass ``reasoning_effort`` on the
+provider config instead — it is forwarded verbatim to ``think``.
+
+Token accounting mirrors :class:`MLXServerProvider`: ``output_tokens``
+is kept as Ollama's ``eval_count`` (total generated tokens, which
+physically includes any thinking output), and ``thinking_tokens`` is a
+whitespace-split estimate of ``message.thinking`` so the Reasoning
+Investment metric is comparable across providers.
+"""
+
+import logging
+import os
+import time
+
+import httpx
+
+from proteus.providers.base import CompletionResult, LLMProvider
+from proteus.providers.thinking_utils import parse_thinking_tags
+
+logger = logging.getLogger(__name__)
+
+# HTTP status codes we retry on. 4xx other than 429 are permanent
+# client errors (auth, malformed payload) and propagate immediately.
+_RETRYABLE_STATUSES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+_BACKOFF_SECONDS: tuple[int, ...] = (1, 2, 4)
+
+
+class OllamaCloudProvider(LLMProvider):
+    """LLM provider backed by Ollama Cloud's native ``/api/chat`` endpoint.
+
+    Routes every request through the native protocol (not the
+    OpenAI-compatible path) so that Qwen3 / GPT-OSS / DeepSeek
+    reasoning models return ``message.thinking`` as a structured field
+    rather than inlining ``<think>`` tags. Falls back to
+    :func:`parse_thinking_tags` when the server happens to inline tags
+    (older deployments, non-cloud tags).
+
+    Args:
+        model: Ollama model tag, e.g. ``"qwen3.5:cloud"`` or
+            ``"gpt-oss:120b-cloud"``. For local Ollama usage the
+            existing ``LocalProvider`` is the better fit — this class
+            targets the hosted cloud path.
+        api_key: Ollama Cloud API key. Falls back to the
+            ``OLLAMA_API_KEY`` environment variable.
+        base_url: Override the cloud host. Defaults to
+            ``https://ollama.com``. Any ``/api/chat`` suffix on the
+            input is stripped before the request is dispatched.
+        max_retries: Retry budget for transient 429/5xx and network
+            errors (exponential backoff: 1s, 2s, 4s).
+        timeout: Request timeout in seconds.
+        top_p: Nucleus sampling parameter (``0.0`` disables).
+        top_k: Top-k sampling parameter (``0`` disables).
+        seed: Deterministic seed.
+        repetition_penalty: Ollama ``repeat_penalty`` option
+            (``0.0`` / ``1.0`` disables).
+        enable_thinking: Forwarded as the Ollama ``think`` field.
+            ``None`` = omit (server default), ``True`` / ``False`` =
+            force on/off. For gpt-oss which expects a level string,
+            use ``reasoning_effort`` instead.
+        reasoning_effort: Level string (``"low"`` / ``"medium"`` /
+            ``"high"``) forwarded to ``think`` for gpt-oss-family
+            models. Takes precedence over ``enable_thinking`` when set.
+    """
+
+    DEFAULT_BASE_URL = "https://ollama.com"
+
+    def __init__(
+        self,
+        model: str = "qwen3.5:cloud",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int = 3,
+        timeout: float = 120.0,
+        top_p: float = 0.0,
+        top_k: int = 0,
+        seed: int | None = None,
+        repetition_penalty: float = 0.0,
+        enable_thinking: bool | None = None,
+        reasoning_effort: str | None = None,
+    ) -> None:
+        self._model = model
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._top_p = top_p
+        self._top_k = top_k
+        self._seed = seed
+        self._repetition_penalty = repetition_penalty
+        self._enable_thinking = enable_thinking
+        self._reasoning_effort = reasoning_effort
+
+        resolved_key = api_key or os.environ.get("OLLAMA_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Ollama Cloud API key must be provided via api_key param "
+                "or OLLAMA_API_KEY environment variable."
+            )
+        self._api_key = resolved_key
+
+        # Normalise the base URL: accept either ``https://ollama.com``
+        # or ``https://ollama.com/api/chat`` — we always POST to /api/chat
+        # internally so duplicate suffixes would break silently.
+        host = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        if host.endswith("/api/chat"):
+            host = host[: -len("/api/chat")]
+        self._base_url = host
+
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+        logger.info(
+            "OllamaCloudProvider targeting %s at %s (thinking=%s, effort=%s)",
+            model, self._base_url, enable_thinking, reasoning_effort,
+        )
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    # ------------------------------------------------------------------
+    # Public entry
+    # ------------------------------------------------------------------
+
+    def complete(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+    ) -> CompletionResult:
+        """Send a non-streaming chat request to Ollama Cloud.
+
+        Args:
+            messages: Chat messages with ``role`` and ``content`` keys.
+                Forwarded verbatim to ``/api/chat`` — Ollama accepts
+                the same role set (``system`` / ``user`` / ``assistant``
+                / ``tool``) we already produce.
+            temperature: Sampling temperature → ``options.temperature``.
+            max_tokens: Max generation tokens → ``options.num_predict``.
+
+        Returns:
+            :class:`CompletionResult` with the answer in ``text`` and the
+            reasoning trace in ``thinking_text`` (``None`` if the model
+            did not reason). ``thinking_tokens`` is a whitespace-split
+            estimate of the thinking text, matching the convention used
+            by :class:`MLXServerProvider` so Reasoning Investment values
+            are comparable across backends.
+        """
+        options: dict[str, object] = {
+            "temperature": temperature,
+            "num_predict": max_tokens,
+        }
+        if self._top_p > 0.0:
+            options["top_p"] = self._top_p
+        if self._top_k > 0:
+            options["top_k"] = self._top_k
+        if self._seed is not None:
+            options["seed"] = self._seed
+        if self._repetition_penalty > 0.0 and self._repetition_penalty != 1.0:
+            options["repeat_penalty"] = self._repetition_penalty
+
+        payload: dict[str, object] = {
+            "model": self._model,
+            "messages": messages,
+            "stream": False,
+            "options": options,
+        }
+
+        # Resolve the ``think`` field. reasoning_effort wins (gpt-oss
+        # needs a level string) and falls back to the boolean toggle.
+        # Absent both → omit so the server default applies.
+        think_value: object | None = None
+        if self._reasoning_effort is not None:
+            think_value = self._reasoning_effort
+        elif self._enable_thinking is not None:
+            think_value = self._enable_thinking
+        if think_value is not None:
+            payload["think"] = think_value
+
+        response_json = self._call_with_retry(payload)
+
+        message = response_json.get("message") or {}
+        text = message.get("content") or ""
+        thinking_text_raw = message.get("thinking") or None
+
+        input_tokens = int(response_json.get("prompt_eval_count") or 0)
+        output_tokens = int(response_json.get("eval_count") or 0)
+        done_reason = response_json.get("done_reason") or "stop"
+
+        # Preferred path: Ollama returned a structured ``thinking``
+        # field (cloud Qwen3 with ``think=true``). Count tokens via
+        # whitespace split — matches parse_thinking_tags so the RI
+        # metric is comparable to MLXServerProvider / CUDAServerProvider.
+        if thinking_text_raw:
+            thinking_text: str | None = thinking_text_raw
+            thinking_tokens = len(thinking_text_raw.split())
+        else:
+            # Fallback: older deployments or non-cloud tags may still
+            # inline <think>...</think> tags in content. Reuse the
+            # shared parser so behaviour stays consistent with other
+            # server-based providers.
+            text, thinking_tokens, thinking_text = parse_thinking_tags(text)
+
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            thinking_tokens=thinking_tokens,
+            thinking_text=thinking_text,
+            logprobs=None,
+            finish_reason=done_reason,
+        )
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _call_with_retry(self, payload: dict) -> dict:
+        """POST ``/api/chat`` with exponential-backoff retries.
+
+        Retries on 429 / 5xx / network errors only. Auth / validation
+        errors (4xx other than 429) surface immediately so the caller
+        sees actionable failure rather than burning the retry budget.
+        """
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.post("/api/chat", json=payload)
+                if response.status_code in _RETRYABLE_STATUSES:
+                    snippet = response.text[:200]
+                    logger.warning(
+                        "Ollama Cloud %d on attempt %d/%d: %s",
+                        response.status_code,
+                        attempt + 1,
+                        self._max_retries + 1,
+                        snippet,
+                    )
+                    last_error = httpx.HTTPStatusError(
+                        f"Ollama Cloud transient {response.status_code}: {snippet}",
+                        request=response.request,
+                        response=response,
+                    )
+                else:
+                    response.raise_for_status()
+                    return response.json()
+            except (
+                httpx.TimeoutException,
+                httpx.ConnectError,
+                httpx.ReadError,
+                httpx.RemoteProtocolError,
+            ) as exc:
+                last_error = exc
+                logger.warning(
+                    "Ollama Cloud network error on attempt %d/%d: %s",
+                    attempt + 1, self._max_retries + 1, exc,
+                )
+            except httpx.HTTPStatusError:
+                # Non-retryable (permanent 4xx). Propagate immediately.
+                raise
+
+            if attempt < self._max_retries:
+                wait = _BACKOFF_SECONDS[
+                    min(attempt, len(_BACKOFF_SECONDS) - 1)
+                ]
+                time.sleep(wait)
+        assert last_error is not None  # loop guarantees at least one
+        raise last_error
+
+    def __del__(self) -> None:
+        # Best-effort cleanup; httpx clients hold a connection pool.
+        client = getattr(self, "_client", None)
+        if client is not None:
+            try:
+                client.close()
+            except Exception:
+                pass

proteus/providers/openai.py

@@ -0,0 +1,432 @@
+"""OpenAI provider for GPT-family and o-series reasoning models.
+
+Dual-path implementation:
+
+- **Chat Completions API** (default): used for non-reasoning models
+  (``gpt-4o``, ``gpt-4-turbo`` etc.). Thinking-token extraction falls
+  back to ``usage.completion_tokens_details.reasoning_tokens`` when the
+  model is an o-series model routed through the legacy chat endpoint.
+
+- **Responses API** (reasoning models): used automatically for
+  ``o1``/``o3``/``o4``/``gpt-5`` models, or when ``use_responses_api=True``
+  is set explicitly. The Responses API is the only OpenAI endpoint that
+  exposes (a) reasoning summaries (``response.output[*].summary[*].text``)
+  and (b) API-reported reasoning tokens
+  (``response.usage.output_tokens_details.reasoning_tokens``). Both are
+  captured into ``CompletionResult.thinking_text`` and
+  ``CompletionResult.thinking_tokens`` respectively.
+
+The ``reasoning_effort`` param is forwarded to the Responses API as
+``reasoning.effort``; requesting a summary is always on (``summary="auto"``)
+so Phase O Unit 15 split-call analyses see thinking_text for the
+linguistic channel (H_thinking_* keyword counts) in the same schema as
+Gemini / Qwen3 providers.
+
+Example configuration::
+
+    provider:
+      type: openai
+      model: o4-mini
+      reasoning_effort: medium      # forwarded to Responses API
+      # api_key: defaults to OPENAI_API_KEY env var
+"""
+
+import logging
+import os
+import time
+
+from openai import OpenAI
+from openai import APIError, APITimeoutError, BadRequestError, RateLimitError
+
+from proteus.providers.base import CompletionResult, LLMProvider
+
+logger = logging.getLogger(__name__)
+
+# Only transient errors are retried. BadRequestError (400 — permanent
+# client-side validation errors such as "org not verified for reasoning
+# summaries") must propagate immediately so the caller's fallback logic
+# can handle it without burning the retry budget.
+_RETRYABLE_EXCEPTIONS = (RateLimitError, APITimeoutError)
+_BACKOFF_SECONDS = (1, 2, 4)
+
+# Model-name prefixes that trigger automatic Responses API routing.
+# All o-series and gpt-5 family models are reasoning models that report
+# reasoning tokens + reasoning summaries only through /v1/responses.
+_REASONING_PREFIXES: tuple[str, ...] = ("o1", "o3", "o4", "gpt-5")
+
+
+def _is_reasoning_model(model: str) -> bool:
+    """Whether *model* should be routed through the Responses API."""
+    return any(model.startswith(p) for p in _REASONING_PREFIXES)
+
+
+class OpenAIProvider(LLMProvider):
+    """LLM provider backed by the OpenAI API.
+
+    Dispatches to Chat Completions (``/v1/chat/completions``) or
+    Responses (``/v1/responses``) based on model family. The Responses
+    path is required for o-series reasoning models to receive the
+    reasoning summary and the API-reported reasoning-token count.
+
+    Args:
+        model: Model identifier (e.g. ``"gpt-4o"`` or ``"o4-mini"``).
+        api_key: OpenAI API key. Falls back to ``OPENAI_API_KEY`` env var.
+        base_url: Optional base URL override for compatible APIs.
+        max_retries: Retry budget on transient errors.
+        timeout: HTTP timeout in seconds.
+        top_p: Nucleus sampling parameter (ignored for reasoning models).
+        seed: Deterministic seed (ignored for reasoning models).
+        logprobs: Request log probabilities (Chat Completions only).
+        reasoning_effort: One of ``"low"``/``"medium"``/``"high"``. When
+            set, overrides auto-detection and forces the Responses API.
+        use_responses_api: Explicit override. ``None`` = auto-detect by
+            model prefix; ``True``/``False`` force one or the other.
+        reasoning_summary: Summary verbosity forwarded to the Responses
+            API (``"auto"`` / ``"concise"`` / ``"detailed"``). Default
+            ``"auto"`` gives the provider best-effort summaries.
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int = 3,
+        timeout: float = 120.0,
+        top_p: float = 0.0,
+        seed: int | None = None,
+        logprobs: bool = False,
+        reasoning_effort: str | None = None,
+        use_responses_api: bool | None = None,
+        reasoning_summary: str = "auto",
+    ) -> None:
+        self._model = model
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._top_p = top_p
+        self._seed = seed
+        self._logprobs = logprobs
+        self._reasoning_effort = reasoning_effort
+        self._reasoning_summary = reasoning_summary
+        # Auto-route reasoning models through the Responses API unless
+        # the caller explicitly opts out. Non-reasoning models stay on
+        # Chat Completions for backward compatibility (deterministic
+        # seeds, logprobs, temperature support).
+        if use_responses_api is None:
+            self._use_responses = _is_reasoning_model(model) or (
+                reasoning_effort is not None
+            )
+        else:
+            self._use_responses = bool(use_responses_api)
+
+        resolved_key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "OpenAI API key must be provided via api_key param "
+                "or OPENAI_API_KEY environment variable."
+            )
+        self._client = OpenAI(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=0,  # Disable SDK-level retries; our provider handles retries
+        )
+
+    @property
+    def model_name(self) -> str:
+        return self._model
+
+    # ------------------------------------------------------------------
+    # Public entry
+    # ------------------------------------------------------------------
+
+    def complete(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+    ) -> CompletionResult:
+        """Send a completion request, dispatching by endpoint family.
+
+        Args:
+            messages: Chat messages with ``role`` and ``content`` keys.
+            temperature: Sampling temperature (ignored on Responses API).
+            max_tokens: Maximum tokens to generate (forwarded as
+                ``max_completion_tokens`` on Chat / ``max_output_tokens``
+                on Responses).
+
+        Returns:
+            CompletionResult. For reasoning models routed through the
+            Responses API, ``thinking_tokens`` is the API-reported
+            ``reasoning_tokens`` count and ``thinking_text`` is the
+            concatenated ``summary_text`` blocks.
+        """
+        if self._use_responses:
+            return self._complete_responses(messages, max_tokens)
+        return self._complete_chat(messages, temperature, max_tokens)
+
+    # ------------------------------------------------------------------
+    # Responses API path (o-series / gpt-5)
+    # ------------------------------------------------------------------
+
+    def _complete_responses(
+        self,
+        messages: list[dict[str, str]],
+        max_tokens: int,
+    ) -> CompletionResult:
+        """Call ``/v1/responses`` and extract summary + reasoning tokens."""
+        input_items = self._messages_to_input(messages)
+
+        reasoning_payload: dict = {}
+        if self._reasoning_summary:
+            reasoning_payload["summary"] = self._reasoning_summary
+        if self._reasoning_effort:
+            reasoning_payload["effort"] = self._reasoning_effort
+
+        kwargs: dict = {
+            "model": self._model,
+            "input": input_items,
+            "max_output_tokens": max_tokens,
+        }
+        if reasoning_payload:
+            kwargs["reasoning"] = reasoning_payload
+
+        try:
+            response = self._call_with_retry(
+                self._client.responses.create, kwargs, endpoint="responses"
+            )
+        except BadRequestError as exc:
+            # Organization-not-verified orgs can still use o-series for
+            # reasoning token accounting, they just cannot receive the
+            # human-readable summary. Detect that specific 400 and retry
+            # without ``summary``. We remember the downgrade so subsequent
+            # calls skip the summary request up-front (cheaper).
+            msg = str(exc)
+            if (
+                "reasoning.summary" in msg
+                or "generate reasoning summaries" in msg
+            ) and "summary" in reasoning_payload:
+                logger.warning(
+                    "OpenAI org not verified for reasoning summaries — "
+                    "falling back to token-only accounting. "
+                    "thinking_text will be None for this model."
+                )
+                self._reasoning_summary = ""
+                reasoning_payload.pop("summary", None)
+                if reasoning_payload:
+                    kwargs["reasoning"] = reasoning_payload
+                else:
+                    kwargs.pop("reasoning", None)
+                response = self._call_with_retry(
+                    self._client.responses.create,
+                    kwargs,
+                    endpoint="responses",
+                )
+            else:
+                raise
+
+        # Usage: prompt / output / reasoning tokens. Shape:
+        #   usage.input_tokens, usage.output_tokens,
+        #   usage.output_tokens_details.reasoning_tokens
+        usage = getattr(response, "usage", None)
+        input_tokens = int(getattr(usage, "input_tokens", 0) or 0) if usage else 0
+        output_tokens = int(getattr(usage, "output_tokens", 0) or 0) if usage else 0
+        reasoning_tokens = 0
+        if usage is not None:
+            details = getattr(usage, "output_tokens_details", None)
+            if details is not None:
+                reasoning_tokens = int(
+                    getattr(details, "reasoning_tokens", 0) or 0
+                )
+
+        # Walk response.output to split reasoning summaries from the
+        # final message content. The Responses API returns a list of
+        # output items; reasoning items carry ``type="reasoning"`` with
+        # a ``summary`` array, and the final answer arrives as
+        # ``type="message"`` with ``content`` list of output_text parts.
+        summary_parts: list[str] = []
+        answer_parts: list[str] = []
+        finish_reason: str | None = None
+        output_items = getattr(response, "output", None) or []
+        for item in output_items:
+            item_type = getattr(item, "type", None)
+            if item_type == "reasoning":
+                for block in getattr(item, "summary", None) or []:
+                    btype = getattr(block, "type", None)
+                    btext = getattr(block, "text", None)
+                    if btype == "summary_text" and btext:
+                        summary_parts.append(btext)
+            elif item_type == "message":
+                for block in getattr(item, "content", None) or []:
+                    btype = getattr(block, "type", None)
+                    btext = getattr(block, "text", None)
+                    if btype in ("output_text", "text") and btext:
+                        answer_parts.append(btext)
+                if finish_reason is None:
+                    finish_reason = getattr(item, "status", None)
+
+        # Fallback: older SDK versions expose a flattened ``output_text``.
+        if not answer_parts:
+            fallback_text = getattr(response, "output_text", None)
+            if fallback_text:
+                answer_parts.append(fallback_text)
+        if finish_reason is None:
+            finish_reason = getattr(response, "status", None)
+
+        text = "\n".join(p for p in answer_parts if p).strip()
+        thinking_text = "\n\n".join(summary_parts).strip() or None
+
+        # If the summary is empty but reasoning tokens were charged, the
+        # model reasoned internally without emitting a summary — still
+        # report the token count so Reasoning Investment accounting is
+        # accurate.
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            thinking_tokens=reasoning_tokens,
+            thinking_text=thinking_text,
+            logprobs=None,
+            finish_reason=finish_reason,
+        )
+
+    # ------------------------------------------------------------------
+    # Chat Completions API path (non-reasoning models)
+    # ------------------------------------------------------------------
+
+    def _complete_chat(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float,
+        max_tokens: int,
+    ) -> CompletionResult:
+        """Call ``/v1/chat/completions`` for non-reasoning models."""
+        kwargs: dict = {
+            "model": self._model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        }
+        if self._top_p > 0.0:
+            kwargs["top_p"] = self._top_p
+        if self._seed is not None:
+            kwargs["seed"] = self._seed
+        if self._logprobs:
+            kwargs["logprobs"] = True
+
+        extra_body = getattr(self, "_extra_body", None)
+        if extra_body:
+            kwargs["extra_body"] = extra_body
+
+        response = self._call_with_retry(
+            self._client.chat.completions.create, kwargs, endpoint="chat"
+        )
+
+        usage = response.usage
+        input_tokens = usage.prompt_tokens if usage else 0
+        output_tokens = usage.completion_tokens if usage else 0
+
+        # API-reported reasoning tokens — present for o-series even when
+        # routed through chat completions (rare but possible via proxy).
+        thinking_tokens = 0
+        if usage is not None:
+            details = getattr(usage, "completion_tokens_details", None)
+            if details is not None:
+                thinking_tokens = int(
+                    getattr(details, "reasoning_tokens", 0) or 0
+                )
+
+        choice = response.choices[0]
+        text = choice.message.content or ""
+        finish_reason = choice.finish_reason
+
+        # Some newer SDK builds surface a ``reasoning_content`` field on
+        # the message (o-series on chat completions, Qwen on compat
+        # proxies). Capture it for the linguistic channel if present.
+        thinking_text: str | None = None
+        msg_data = (
+            choice.message.model_dump()
+            if hasattr(choice.message, "model_dump")
+            else {}
+        )
+        reasoning_text = (
+            msg_data.get("reasoning_content")
+            or msg_data.get("reasoning")
+            or ""
+        )
+        if reasoning_text:
+            thinking_text = reasoning_text
+            # If API reported 0 reasoning_tokens but text exists, fall
+            # back to whitespace split as a last-resort estimate so RI
+            # is non-zero.
+            if thinking_tokens == 0:
+                thinking_tokens = len(reasoning_text.split())
+            if not text:
+                text = reasoning_text
+
+        logprobs_list: list[float] | None = None
+        if choice.logprobs and choice.logprobs.content:
+            logprobs_list = [tok.logprob for tok in choice.logprobs.content]
+
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            thinking_tokens=thinking_tokens,
+            thinking_text=thinking_text,
+            logprobs=logprobs_list,
+            finish_reason=finish_reason,
+        )
+
+    # ------------------------------------------------------------------
+    # Shared helpers
+    # ------------------------------------------------------------------
+
+    def _call_with_retry(self, fn, kwargs: dict, *, endpoint: str):
+        """Exponential-backoff retry wrapper shared by both endpoints."""
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                return fn(**kwargs)
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_error = exc
+                if attempt < self._max_retries:
+                    wait = _BACKOFF_SECONDS[
+                        min(attempt, len(_BACKOFF_SECONDS) - 1)
+                    ]
+                    logger.warning(
+                        "OpenAI %s request failed (attempt %d/%d): %s. "
+                        "Retrying in %ds...",
+                        endpoint,
+                        attempt + 1,
+                        self._max_retries + 1,
+                        exc,
+                        wait,
+                    )
+                    time.sleep(wait)
+        raise last_error  # type: ignore[misc]
+
+    @staticmethod
+    def _messages_to_input(
+        messages: list[dict[str, str]],
+    ) -> list[dict[str, object]]:
+        """Convert Chat-style messages to Responses API ``input`` shape.
+
+        The Responses API accepts either a bare string or a list of
+        message-like items. Each item has ``role`` and ``content`` where
+        ``content`` is a list of typed parts — ``input_text`` for user
+        / system input, ``output_text`` reserved for model echoes.
+        """
+        input_items: list[dict[str, object]] = []
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            input_items.append(
+                {
+                    "role": role,
+                    "content": [
+                        {"type": "input_text", "text": content}
+                    ],
+                }
+            )
+        return input_items

tests/providers/test_real_providers_ported.py

@@ -0,0 +1,31 @@
+import pathlib
+
+PORTED = ["openai.py", "anthropic_provider.py", "gemini.py", "ollama_cloud.py"]
+
+
+def _providers_dir():
+    return pathlib.Path(__file__).parent.parent.parent / "proteus" / "providers"
+
+
+def test_ported_cloud_providers_exist():
+    root = _providers_dir()
+    missing = [n for n in PORTED if not (root / n).is_file()]
+    assert missing == [], f"missing ported providers: {missing}"
+
+
+def test_ported_providers_have_no_squid_game_references():
+    root = _providers_dir()
+    offenders = [
+        n for n in PORTED
+        if "squid_game" in (root / n).read_text(encoding="utf-8")
+    ]
+    assert offenders == [], f"ported providers still reference squid_game: {offenders}"
+
+
+def test_ported_providers_import_proteus_base():
+    root = _providers_dir()
+    missing = [
+        n for n in PORTED
+        if "from proteus.providers.base import" not in (root / n).read_text(encoding="utf-8")
+    ]
+    assert missing == [], f"ported providers missing proteus base import: {missing}"