Chore(unification): WIP

Author: Mateusz

src/connectors/_openai_codex_connector.py

@@ -1902,132 +1902,15 @@ async def _prepare_payload(
             )
         return payload
 
-    def _normalize_chat_completions_request(
-        self, *args: Any, **kwargs: Any
-    ) -> ConnectorChatCompletionsRequest:
-        """Normalize canonical and legacy invocation shapes into one request contract."""
-        if len(args) == 1 and isinstance(args[0], ConnectorChatCompletionsRequest):
-            if kwargs:
-                unexpected = ", ".join(sorted(kwargs))
-                raise TypeError(
-                    "OpenAICodexConnector.chat_completions received unexpected keyword "
-                    f"arguments with canonical request: {unexpected}"
-                )
-            return args[0]
-
-        if len(args) > 1 and isinstance(args[0], ConnectorChatCompletionsRequest):
-            raise TypeError(
-                "OpenAICodexConnector.chat_completions received too many positional "
-                "arguments with canonical request invocation."
-            )
-
-        if (
-            "request" in kwargs
-            and isinstance(kwargs["request"], ConnectorChatCompletionsRequest)
-            and not args
-        ):
-            canonical_request = cast(
-                ConnectorChatCompletionsRequest, kwargs.pop("request")
-            )
-            if kwargs:
-                unexpected = ", ".join(sorted(kwargs))
-                raise TypeError(
-                    "OpenAICodexConnector.chat_completions received unexpected keyword "
-                    f"arguments with canonical request: {unexpected}"
-                )
-            return canonical_request
-
-        legacy_fields = (
-            "request_data",
-            "processed_messages",
-            "effective_model",
-            "identity",
-            "cancellation_token",
-            "cancellation_coordinator",
-            "context",
-        )
-        if len(args) > len(legacy_fields):
-            raise TypeError(
-                "OpenAICodexConnector.chat_completions expected at most "
-                f"{len(legacy_fields)} positional arguments for legacy invocation, "
-                f"got {len(args)}."
-            )
-
-        legacy_values: dict[str, Any] = {}
-        for index, value in enumerate(args):
-            field_name = legacy_fields[index]
-            if field_name in kwargs:
-                raise TypeError(
-                    "OpenAICodexConnector.chat_completions got multiple values for "
-                    f"argument '{field_name}'."
-                )
-            legacy_values[field_name] = value
-
-        for field_name in legacy_fields:
-            if field_name in kwargs:
-                legacy_values[field_name] = kwargs.pop(field_name)
-
-        if "request" in kwargs and "request_data" not in legacy_values:
-            legacy_values["request_data"] = kwargs.pop("request")
-
-        options_value = kwargs.pop("options", None)
-
-        missing = object()
-        request_data = legacy_values.get("request_data", missing)
-        if request_data is missing:
-            raise TypeError(
-                "OpenAICodexConnector.chat_completions missing required argument "
-                "'request_data' (or canonical 'request')."
-            )
-
-        processed_messages = legacy_values.get("processed_messages", missing)
-        if processed_messages is missing or processed_messages is None:
-            request_messages = getattr(request_data, "messages", None)
-            if isinstance(request_messages, list | tuple):
-                processed_messages = list(request_messages)
-            else:
-                processed_messages = []
-
-        effective_model_value = legacy_values.get("effective_model", missing)
-        if isinstance(effective_model_value, str) and effective_model_value:
-            effective_model = effective_model_value
-        else:
-            model_hint = getattr(request_data, "model", None)
-            if isinstance(model_hint, str) and model_hint:
-                effective_model = model_hint
-            elif effective_model_value is missing:
-                raise TypeError(
-                    "OpenAICodexConnector.chat_completions missing required argument "
-                    "'effective_model'."
-                )
-            else:
-                effective_model = str(effective_model_value)
-
-        normalized_options: dict[str, Any] = {}
-        if isinstance(options_value, dict):
-            normalized_options.update(options_value)
-        elif options_value is not None:
-            normalized_options["options"] = options_value
-        if kwargs:
-            normalized_options.update(kwargs)
-
-        return ConnectorChatCompletionsRequest(
-            request=request_data,
-            processed_messages=processed_messages,
-            effective_model=effective_model,
-            identity=legacy_values.get("identity"),
-            cancellation_token=legacy_values.get("cancellation_token"),
-            cancellation_coordinator=legacy_values.get("cancellation_coordinator"),
-            context=legacy_values.get("context"),
-            options=normalized_options,
-        )
-
-    async def chat_completions(  # type: ignore[override]
+    async def chat_completions(
         self,
-        *args: Any,
-        **kwargs: Any,
+        request: ConnectorChatCompletionsRequest,
     ) -> ResponseEnvelope | StreamingResponseEnvelope:
-        request = self._normalize_chat_completions_request(*args, **kwargs)
+        if not isinstance(request, ConnectorChatCompletionsRequest):
+            raise TypeError(
+                "OpenAICodexConnector.chat_completions() requires a "
+                "ConnectorChatCompletionsRequest instance."
+            )
 
         # Structural enforcement: check cancellation immediately if coordinator and token provided
         if (

src/connectors/base.py

@@ -256,16 +256,9 @@ async def chat_completions(
         Forwards a chat completion request to the LLM backend.
 
         Args:
-            request_data: The request payload as a domain `ChatRequest`.
-            processed_messages: The list of messages after command processing.
-            effective_model: The model name to be used after considering any overrides.
-            identity: Application identity configuration for authentication.
-            cancellation_token: Optional session key for cancellation scoping.
-                If provided, enables cancellation gating and work registration.
-            cancellation_coordinator: Optional cancellation coordinator for structural enforcement.
-                If provided along with cancellation_token, enables connector-level cancellation checks
-                immediately before HTTP request transmission.
-            **kwargs: Additional keyword arguments for the backend.
+            request: Canonical connector request containing the domain chat payload,
+                processed messages, effective model, optional identity and cancellation
+                fields, connector-facing context, and JSON-safe provider options.
 
         Returns:
             Either a ResponseEnvelope for non-streaming requests or

src/connectors/contracts/__init__.py

@@ -54,9 +54,8 @@ class ConnectorRequestContext(InternalDTO):
 class ConnectorChatCompletionsRequest(InternalDTO):
     """Canonical connector-facing request contract.
 
-    Bundles all inputs needed for connector invocation in a single typed contract.
-    This replaces the permissive dict[str, Any] and **kwargs patterns used
-    in the legacy connector API.
+    Bundles all inputs needed for connector invocation in a single typed contract
+    at the connector entry boundary.
 
     Attributes:
         request: Canonical chat request payload
@@ -85,10 +84,7 @@ class ICanonicalChatCompletionsBackend(Protocol):
     Connectors implementing this protocol receive typed contracts and
     return typed response envelopes, eliminating dict/Any leakage at the boundary.
 
-    This protocol defines the canonical connector API that should be used
-    for all new connector implementations. Legacy connectors continue to
-    use LLMBackend.chat_completions() with permissive signatures, but
-    core orchestration will prefer this canonical API when available.
+    Core orchestration invokes backends through this contract.
 
     The protocol is transport-agnostic and does not depend on FastAPI/Starlette types.
     """

src/connectors/gemini_base/connector.py

@@ -1611,53 +1611,16 @@ async def _ensure_healthy(self) -> None:
             self._health_checked = True
             logger.info("Backend health check completed - ready for use")
 
-    async def chat_completions(  # type: ignore[override]
+    async def chat_completions(
         self,
-        request: ConnectorChatCompletionsRequest | Any = None,
-        *args: Any,
-        **kwargs: Any,
+        request: ConnectorChatCompletionsRequest,
     ) -> ResponseEnvelope | StreamingResponseEnvelope:
-        if isinstance(request, ConnectorChatCompletionsRequest):
-            return await self._chat_completions_canonical(request)
-
-        legacy_request_data = kwargs.pop("request_data", request)
-        legacy_processed_messages = kwargs.pop(
-            "processed_messages", args[0] if args else []
-        )
-        legacy_effective_model = kwargs.pop(
-            "effective_model", args[1] if len(args) > 1 else "unknown"
-        )
-        legacy_context = kwargs.pop("context", None)
-        normalized_effective_model = self._resolve_internal_effective_model(
-            legacy_effective_model
-        )
-
-        stream = getattr(legacy_request_data, "stream", False) or kwargs.get(
-            "stream", False
-        )
-        if stream:
-            return await self._chat_completions_code_assist_streaming(
-                request_data=legacy_request_data,
-                processed_messages=(
-                    list(legacy_processed_messages)
-                    if not isinstance(legacy_processed_messages, list)
-                    else legacy_processed_messages
-                ),
-                effective_model=normalized_effective_model,
-                context=legacy_context,
-                **kwargs,
+        if not isinstance(request, ConnectorChatCompletionsRequest):
+            raise TypeError(
+                "GeminiOAuthBaseConnector.chat_completions() requires a "
+                "ConnectorChatCompletionsRequest instance."
             )
-        return await self._chat_completions_code_assist(
-            request_data=legacy_request_data,
-            processed_messages=(
-                list(legacy_processed_messages)
-                if not isinstance(legacy_processed_messages, list)
-                else legacy_processed_messages
-            ),
-            effective_model=normalized_effective_model,
-            context=legacy_context,
-            **kwargs,
-        )
+        return await self._chat_completions_canonical(request)
 
     def _resolve_internal_effective_model(self, effective_model: str) -> str:
         model_name = effective_model

src/connectors/gemini_cloud_project.py

@@ -53,7 +53,7 @@
 import uuid
 from collections.abc import AsyncGenerator, Callable, Sequence
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any
 
 import google.auth
 import google.auth.transport.requests
@@ -1292,125 +1292,17 @@ async def _ensure_healthy(self) -> None:
             if logger.isEnabledFor(logging.INFO):
                 logger.info("Health check passed - backend is ready for use")
 
-    _LEGACY_CHAT_COMPLETIONS_PARAM_ORDER: tuple[str, ...] = (
-        "request_data",
-        "processed_messages",
-        "effective_model",
-        "identity",
-        "cancellation_token",
-        "cancellation_coordinator",
-        "context",
-        "options",
-    )
-
-    def _normalize_chat_completions_request(
-        self,
-        request: ConnectorChatCompletionsRequest | None,
-        args: tuple[Any, ...],
-        kwargs: dict[str, Any],
-    ) -> ConnectorChatCompletionsRequest:
-        """Normalize canonical and legacy invocation shapes into one request object."""
-        if isinstance(request, ConnectorChatCompletionsRequest):
-            if args or kwargs:
-                raise TypeError(
-                    "GeminiCloudProjectConnector.chat_completions() canonical invocation accepts only "
-                    "the `request` argument."
-                )
-            return request
-
-        legacy_values: dict[str, Any] = {}
-        legacy_kwargs = dict(kwargs)
-
-        positional_values: list[Any] = []
-        if request is not None:
-            positional_values.append(request)
-        positional_values.extend(args)
-
-        max_positional = len(self._LEGACY_CHAT_COMPLETIONS_PARAM_ORDER)
-        if len(positional_values) > max_positional:
-            raise TypeError(
-                "GeminiCloudProjectConnector.chat_completions() takes at most "
-                f"{max_positional} legacy positional arguments "
-                f"({len(positional_values)} given)."
-            )
-
-        for index, value in enumerate(positional_values):
-            param_name = self._LEGACY_CHAT_COMPLETIONS_PARAM_ORDER[index]
-            if param_name in legacy_kwargs:
-                raise TypeError(
-                    "GeminiCloudProjectConnector.chat_completions() got multiple values for "
-                    f"argument '{param_name}'."
-                )
-            legacy_values[param_name] = value
-
-        for param_name in self._LEGACY_CHAT_COMPLETIONS_PARAM_ORDER:
-            if param_name in legacy_kwargs:
-                legacy_values[param_name] = legacy_kwargs.pop(param_name)
-
-        required_legacy = self._LEGACY_CHAT_COMPLETIONS_PARAM_ORDER[:3]
-        missing_required = [
-            name for name in required_legacy if name not in legacy_values
-        ]
-        if missing_required:
-            raise TypeError(
-                "GeminiCloudProjectConnector.chat_completions() missing required arguments: "
-                f"{', '.join(missing_required)}. "
-                "Provide canonical `request` or legacy "
-                "`request_data`, `processed_messages`, and `effective_model`."
-            )
-
-        processed_messages_raw = legacy_values["processed_messages"]
-        if processed_messages_raw is None:
-            processed_messages_seq: Sequence[ChatMessage] = ()
-        elif isinstance(processed_messages_raw, Sequence):
-            processed_messages_seq = cast(Sequence[ChatMessage], processed_messages_raw)
-        else:
-            raise TypeError(
-                "GeminiCloudProjectConnector.chat_completions() legacy `processed_messages` "
-                "must be a sequence."
-            )
-
-        effective_model = legacy_values["effective_model"]
-        if not isinstance(effective_model, str):
-            raise TypeError(
-                "GeminiCloudProjectConnector.chat_completions() legacy `effective_model` "
-                "must be a string."
-            )
-
-        options_from_legacy = legacy_values.get("options")
-        if options_from_legacy is None:
-            options: dict[str, Any] = {}
-        elif isinstance(options_from_legacy, dict):
-            options = dict(options_from_legacy)
-        else:
-            raise TypeError(
-                "GeminiCloudProjectConnector.chat_completions() legacy `options` must be a dict."
-            )
-        options.update(legacy_kwargs)
-
-        return ConnectorChatCompletionsRequest(
-            request=legacy_values["request_data"],
-            processed_messages=processed_messages_seq,
-            effective_model=effective_model,
-            identity=legacy_values.get("identity"),
-            cancellation_token=legacy_values.get("cancellation_token"),
-            cancellation_coordinator=legacy_values.get("cancellation_coordinator"),
-            context=legacy_values.get("context"),
-            options=options,
-        )
-
-    async def chat_completions(  # type: ignore[override]
+    async def chat_completions(
         self,
-        request: ConnectorChatCompletionsRequest | None = None,
-        *args: Any,
-        **kwargs: Any,
+        request: ConnectorChatCompletionsRequest,
     ) -> ResponseEnvelope | StreamingResponseEnvelope:
         """Handle chat completions using Google Code Assist API with user's GCP project."""
-        connector_request = self._normalize_chat_completions_request(
-            request=request,
-            args=args,
-            kwargs=kwargs,
-        )
+        if not isinstance(request, ConnectorChatCompletionsRequest):
+            raise TypeError(
+                "GeminiCloudProjectConnector.chat_completions() requires a "
+                "ConnectorChatCompletionsRequest instance."
+            )
+        connector_request = request
         # Structural enforcement: check cancellation immediately if coordinator and token provided
         if (
             connector_request.cancellation_coordinator is not None
@@ -1424,8 +1316,7 @@ async def chat_completions(  # type: ignore[override]
         processed_messages = connector_request.processed_messages
         effective_model = connector_request.effective_model
 
-        # Options not specifically used here but available in request.options if needed
-        # kwargs was previously passed down to _chat_completions_streaming / _chat_completions_standard
+        # Provider-specific options flow through ``ConnectorChatCompletionsRequest.options``.
         kwargs = dict(connector_request.options) if connector_request.options else {}
 
         # Runtime validation with descriptive errors