client_interface.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/client_interface.py
 
"""
Provider-agnostic client wrapper.
 
Purpose
-------
:class:`ClientInterface` is the single thing the rest of OC Chat talks
to for LLM API calls. It holds the active :class:`ProviderPlugin` plus
the underlying SDK client built by that provider, and routes outgoing
messages through the provider's transform / response-parsing hooks.
 
The kwargs accepted by :meth:`stream_chat` and :meth:`one_shot` are the
*existing* DeepSeek-shaped names (``effort``, ``extra_body``,
``max_tokens``) for now, so the swap from ``DeepSeekClient`` to
``ClientInterface`` is a pure rename at every call site. Phase C.3e
will retire ``extra_body`` in favour of ``enable_thinking`` + the
provider's :meth:`build_extra_body` hook.
 
Responsibilities
----------------
- Build the underlying SDK client at construction (env-var lookup for
  API key + base URL, with explicit overrides for tests).
- :meth:`stream_chat` — yield ``(chunk_type, data)`` tuples for streaming
  ReAct iterations, after running the provider's outgoing-message
  transform if tool schemas are supplied.
- :meth:`one_shot` — single non-streaming call, used by context
  compression for the summarisation step.
- :meth:`list_models`, :meth:`parse_usage` — pass-through helpers to
  the provider / SDK.
 
Diagnostics
-----------
Domain: OC_CHAT.CLIENT
Levels:
    L2 — entry into stream_chat / one_shot (one line per call).
    L3 — api_stream / api_one_shot timings via ``dbg_timed``.
    L4 — provider transform decisions (currently unused).
 
Contracts
---------
- Constructor never reads from disk and never makes a network call;
  the SDK client is built lazily by the provider's ``build_client``.
- ``stream_chat`` is a generator; iteration order matches the SDK's.
- ``one_shot`` returns a plain ``str`` — never ``None``.
- All errors are surfaced by the underlying SDK; this wrapper does not
  catch or normalise them.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.provider_plugin (ProviderPlugin ABC and registry singleton)
- oc_chat.core.cancellation (CancellationToken, CancellationError - the per-chunk cancellation check in stream_chat)
- oc_chat.core.egress_guard (lazy; is_forbidden_provider_host - refuses a base URL at a forbidden internal address)
- oc_chat.core.provider_oauth (lazy; resolve_api_key - the provider's API key at construction)
- oc_chat.core.request_plan (lazy; build_request_plan - the provider-neutral request IR for stream_chat)
 
See Also
--------
oc_chat/docs/conventions/CONTRACTS.md §5 Streaming chunk tuples — owner of the
engine-side stream_chat tuple contract.
"""
from __future__ import annotations
 
from typing import Any, Iterator
 
from oc_diagnostics import _dbg, dbg_timed
 
from oc_chat.core.provider_plugin import ProviderPlugin, BaseClient, UsageStats, PerformanceStats, ProviderEndpoint, render_request
from oc_chat.core.cancellation import CancellationToken, CancellationError
 
 
class ClientInterface:
    """Wrap a :class:`ProviderPlugin` + its SDK client behind one façade.
 
    Constructor reads the API key and base URL from the env vars the
    provider declares (``api_key_env_var`` / ``base_url_env_var``);
    callers may pass them explicitly to override (useful in tests).
    """
 
    def __init__(
        self,
        provider: ProviderPlugin,
        *,
        api_key: str | None = None,
        base_url: str | None = None,
    ) -> None:
        import os
        self.provider = provider
        from oc_chat.core.provider_oauth import resolve_api_key
        key = resolve_api_key(provider, api_key)
        url = (
            base_url
            if base_url is not None
            else os.getenv(provider.base_url_env_var, "") or provider.default_base_url
        )
        # M8.0 WU-4c (F72): refuse binding the provider channel to a forbidden
        # internal address (IMDS / link-local / multicast / reserved) -- e.g. a
        # .env-injected base_url. Cloud (public) and Ollama loopback/LAN stay legal.
        from oc_chat.core.egress_guard import is_forbidden_provider_host
        if is_forbidden_provider_host(url):
            raise PermissionError(f"provider base_url is a forbidden internal address: {url}")
        self._client: BaseClient = provider.build_client(key, url)
        self._api_key = key
 
    def rebind_to(self, endpoint: "ProviderEndpoint") -> None:
        """Rebuild the underlying SDK client against *endpoint* (Phase O2).
 
        Used by the ``/endpoint use <name>`` slash command to swap the
        active base URL at runtime without restarting OC Chat. The API
        key (read at construction time) is reused; only the base URL
        changes. ModelManager cache invalidation is the caller's
        responsibility — :func:`oc_chat.core.commands.cmd_endpoint`
        already handles it.
        """
        func = "ClientInterface.rebind_to"
        _dbg("OC_CHAT.CLIENT", func, f"endpoint={endpoint.name} url={endpoint.base_url}", 2)
        from oc_chat.core.egress_guard import is_forbidden_provider_host
        if is_forbidden_provider_host(endpoint.base_url):
            raise PermissionError(
                f"endpoint {endpoint.name!r} base_url is a forbidden internal address: {endpoint.base_url}"
            )
        self._client = self.provider.build_client(self._api_key, endpoint.base_url)
 
    # ── Prepared/apply transition primitives (plan 152 D4 / ADR-2) ──────────
 
    def build_candidate(self, endpoint: "ProviderEndpoint") -> BaseClient:
        """Build an UNATTACHED SDK client for *endpoint* — the PREPARE half.
 
        Does everything :meth:`rebind_to` does EXCEPT assigning ``_client``:
        enforces the M8.0 WU-4c forbidden-host policy and calls the provider's
        ``build_client``. Both are fallible, which is exactly why they belong in
        PREPARE — the live client is untouched, so a raise here leaves the whole
        old tuple intact and the transition aborts fail-closed.
 
        The returned object is inert until :meth:`install_prepared` publishes it.
        Callers must NOT reach for the private ``_client`` themselves.
        """
        func = "ClientInterface.build_candidate"
        _dbg("OC_CHAT.CLIENT", func, f"endpoint={endpoint.name} url={endpoint.base_url}", 2)
        from oc_chat.core.egress_guard import is_forbidden_provider_host
        if is_forbidden_provider_host(endpoint.base_url):
            raise PermissionError(
                f"endpoint {endpoint.name!r} base_url is a forbidden internal address: {endpoint.base_url}"
            )
        return self.provider.build_client(self._api_key, endpoint.base_url)
 
    def install_prepared(self, built: BaseClient) -> None:
        """Publish a client built by :meth:`build_candidate` — the COMMIT half.
 
        A pure assignment: no rebuild, no policy re-run (policy already ran in
        PREPARE, on this exact object's endpoint). Cannot raise, which is what
        lets the transition's commit block be a no-fail critical section.
        """
        func = "ClientInterface.install_prepared"
        self._client = built
        _dbg("OC_CHAT.CLIENT", func, "installed prepared client", 2)
 
    # ── Streaming chat ──────────────────────────────────────────────────────
 
    def stream_chat(
        self,
        messages: list[dict],
        model: str,
        effort: str | None = None,
        extra_body: dict | None = None,
        tools: list | None = None,
        max_tokens: int | None = None,
        *,
        tool_schemas: list[dict] | None = None,
        cancellation: CancellationToken | None = None,
    ) -> Iterator[tuple[str, Any]]:
        """Stream a chat completion. Yields ``(chunk_type, data)`` tuples.
 
        Chunk types: ``"reasoning"``, ``"content"``, ``"tool_call"``,
        ``"usage"``, ``"finish_reason"`` — same shape as
        ``DeepSeekClient.stream_chat``. ``"finish_reason"`` is optional:
        a provider that cannot report one simply never yields it, and
        consumers must treat its absence as "unknown", not as "stop".
 
        The request is assembled through the provider-neutral request IR
        (plan 135 §3.4): a :class:`ProviderRequestPlan` is built here and the
        provider's :meth:`render_request` shapes the wire request. For chat
        providers the default renderer reproduces ``messages[0]`` byte-for-byte.
        *tool_schemas* is accepted for call-site compatibility; the tool catalog
        sent to the API comes from *tools* (the schema-embedding transform is
        retired).
 
        If *cancellation* is provided, each yielded chunk is preceded by a
        check; a cancelled token raises :class:`CancellationError`.
        """
        func = "stream_chat"
        _dbg("OC_CHAT.CLIENT", func,
             f"model={model} effort={effort} tools={'yes' if tools else 'no'} max_tokens={max_tokens}", 2)
        # Plan 135 §3.4/§4.5: build the provider-neutral request IR at the assembly
        # point and let the provider render it. The default (OpenAI-Chat) renderer
        # reproduces messages[0] byte-for-byte; effort/extra_body keep their
        # caller-side ownership. ``None``-vs-``[]`` for tools is preserved via the
        # fallback below, so chat behaviour is byte/semantically unchanged.
        # (transform_outgoing_messages is retired — render_request is the seam.)
        from oc_chat.core.request_plan import build_request_plan
        plan = build_request_plan(
            messages,
            model,
            tool_catalog=tools,
            reasoning_mode=(effort or "off"),
            output_max_tokens=max_tokens,
        )
        rendered = render_request(self.provider, plan)
        out_tools = rendered.tools if rendered.tools is not None else tools
        out_extra_body = rendered.extra_body if rendered.extra_body is not None else extra_body
        out_max_tokens = rendered.max_tokens if rendered.max_tokens is not None else max_tokens
        with dbg_timed("OC_CHAT.CLIENT", func, label="api_stream", level=3):
            for chunk in self._client.stream_chat(
                rendered.messages,
                model,
                effort=effort,
                extra_body=out_extra_body,
                tools=out_tools,
                max_tokens=out_max_tokens,
                cancellation=cancellation,
            ):
                if cancellation is not None:
                    cancellation.raise_if_cancelled()
                yield chunk
 
    # ── One-shot (non-streaming) ────────────────────────────────────────────
 
    def one_shot(
        self,
        messages: list[dict],
        model: str,
        *,
        effort: str | None = None,
        extra_body: dict | None = None,
        max_tokens: int | None = None,
    ) -> str:
        """Non-streaming single call. Used for context compression summaries."""
        func = "one_shot"
        _dbg("OC_CHAT.CLIENT", func,
             f"model={model} effort={effort} max_tokens={max_tokens}", 2)
        with dbg_timed("OC_CHAT.CLIENT", func, label="api_one_shot", level=3):
            return self._client.one_shot(
                messages,
                model,
                effort=effort,
                extra_body=extra_body,
                max_tokens=max_tokens,
            )
 
    # ── Auxiliary ───────────────────────────────────────────────────────────
 
    def list_models(self) -> list[str]:
        """Return the live model id list from the underlying API."""
        return self._client.list_models()
 
    def parse_usage(self, usage: dict) -> UsageStats:
        """Normalise an API usage block into :class:`UsageStats`."""
        return self.provider.parse_usage(usage)
 
    def parse_performance(self, chunk: dict) -> PerformanceStats:
        """Extract tok/s performance data from the final usage chunk."""
        return self.provider.parse_performance(chunk)