provider_plugin.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/provider_plugin.py
 
"""
Provider plugin abstraction — harness re-export + harness-coupled glue.
 
Purpose
-------
Plan 154 relocated the provider-plugin *contract* (the ``ProviderPlugin``
ABC, the typed shapes ``ModelCaps`` / ``UsageStats`` / ``PerformanceStats``
/ ``ModelInfo`` / ``ProviderEndpoint``, the ``BaseClient`` Protocol, and the
``ProviderRegistry`` + ``registry`` singleton) into the shared leaf
``option_c_agent_contracts.provider_plugin`` so provider bundles depend only
on that leaf and never import ``oc_chat`` (breaking the
``providers -> oc_chat.core`` cycle named in plan 151 §8).
 
This module re-exports that contract surface unchanged, so the ~15 harness
call sites that do ``from oc_chat.core.provider_plugin import ...`` keep
working byte-for-byte. It ALSO owns the two default behaviours that carried
harness dependencies and therefore could not live in the pure leaf:
:func:`render_request` (needs ``oc_chat.core.request_plan``) and
:func:`endpoints` (needs ``oc_chat.core.endpoint_registry``). They are free
functions here (no provider overrides either, verified at dispatch), with an
override-delegation hook preserved for future providers.
 
Responsibilities
----------------
- Re-export the provider-plugin contract from the leaf.
- :func:`render_request` — render a :class:`ProviderRequestPlan` to the wire
  shape (OpenAI-Chat-compatible default).
- :func:`endpoints` — synthesise the provider's named base-URL targets.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- The re-exported names are identical objects to the leaf's — an
  ``isinstance`` / registration against either import path is equivalent.
- :func:`render_request` / :func:`endpoints` delegate to a provider-defined
  method of the same name when one exists (future extension), else apply the
  default.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- option_c_agent_contracts.provider_plugin (the relocated contract)
- oc_chat.core.endpoint_registry (lazy; classify_lan_policy for the default endpoint)
- oc_chat.core.request_plan (lazy; RenderedRequest and the chat composers for render_request)
"""
from __future__ import annotations
 
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
from option_c_agent_contracts.provider_plugin import (
    BaseClient,
    ModelCaps,
    ModelInfo,
    PerformanceStats,
    ProviderEndpoint,
    ProviderPlugin,
    ProviderRegistry,
    SupportsCancellation,
    UsageStats,
    registry,
)
 
if TYPE_CHECKING:
    from oc_chat.core.request_plan import ProviderRequestPlan, RenderedRequest
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
def render_request(provider: ProviderPlugin, plan: "ProviderRequestPlan") -> "RenderedRequest":
    """Render a provider-neutral :class:`ProviderRequestPlan` to the wire shape.
 
    Default = OpenAI-Chat-compatible (plan 135 §3.4): recompose the chat
    ``messages`` list (``messages[0]`` reproduced byte-for-byte from
    ``policy_prompt + tool_reference``), narrow the tool catalog to
    ``allowed_tools``, and leave ``system`` as ``None`` (the system prompt
    lives in ``messages[0]`` for chat providers; ``effort``/``extra_body``
    keep their caller-side ownership). DeepSeek/ollama/example inherit this;
    the future Anthropic bundle (plan 137) supplies its own ``render_request``
    method, which this function delegates to when present.
 
    Relocated out of the ``ProviderPlugin`` ABC by plan 154 because the pure
    contract leaf must not import ``oc_chat.core.request_plan``.
    """
    override = getattr(type(provider), "render_request", None)
    if callable(override):
        return override(provider, plan)
 
    from oc_chat.core.request_plan import (
        RenderedRequest,
        compose_chat_messages,
        filtered_tool_catalog,
    )
 
    return RenderedRequest(
        messages=compose_chat_messages(plan),
        tools=filtered_tool_catalog(plan),
        extra_body=None,
        max_tokens=plan.output_max_tokens,
        system=None,
    )
 
 
def endpoints(provider: ProviderPlugin) -> dict[str, ProviderEndpoint]:
    """Return the named base-URL targets *provider* can serve (Phase O2).
 
    Default implementation synthesises exactly one entry named ``"default"``
    whose ``base_url`` is read from ``os.environ[provider.base_url_env_var]``
    when set, else :attr:`ProviderPlugin.default_base_url`. LAN policy is
    classified by ``oc_chat.core.endpoint_registry.classify_lan_policy``.
 
    A provider can expose multiple curated endpoints by defining its own
    ``endpoints`` method, which this function delegates to when present; the
    registry layer (env var + ``~/.oc_chat/endpoints.toml``) merges on top.
 
    Relocated out of the ``ProviderPlugin`` ABC by plan 154 because the pure
    contract leaf must not import ``oc_chat.core.endpoint_registry``.
    """
    override = getattr(type(provider), "endpoints", None)
    if callable(override):
        return override(provider)
 
    import os
    from oc_chat.core.endpoint_registry import classify_lan_policy
 
    if provider.base_url_env_var:
        base_url = os.environ.get(provider.base_url_env_var, provider.default_base_url)
    else:
        base_url = provider.default_base_url
    if not base_url:
        return {}
    policy = classify_lan_policy(base_url)
    return {"default": ProviderEndpoint(name="default", base_url=base_url, lan_policy_status=policy)}
 
 
__all__ = [
    "ModelCaps",
    "UsageStats",
    "PerformanceStats",
    "ModelInfo",
    "ProviderEndpoint",
    "BaseClient",
    "SupportsCancellation",
    "ProviderPlugin",
    "ProviderRegistry",
    "registry",
    "render_request",
    "endpoints",
]