ccproxy-api 0.1.7__py3-none-any.whl → 0.2.0a4__py3-none-any.whl

ccproxy/services/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Adapter subpackage exports."""
+
+from .format_adapter import DictFormatAdapter, FormatAdapterProtocol
+from .format_registry import FormatRegistry
+
+
+__all__ = [
+    "FormatAdapterProtocol",
+    "DictFormatAdapter",
+    "FormatRegistry",
+]

ccproxy/services/adapters/base.py

@@ -0,0 +1,123 @@
+"""Base adapter for provider plugins."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from fastapi import Request
+from starlette.responses import Response, StreamingResponse
+
+from ccproxy.streaming import DeferredStreaming
+
+
+class BaseAdapter(ABC):
+    """Base adapter for provider-specific request handling."""
+
+    def __init__(self, config: Any, **kwargs: Any) -> None:
+        """Initialize the base adapter.
+
+        Args:
+            config: Plugin configuration
+            **kwargs: Additional keyword arguments for subclasses
+        """
+        self.config = config
+        self.tool_accumulator_class = kwargs.pop("tool_accumulator_class", None)
+
+    @abstractmethod
+    async def handle_request(
+        self, request: Request
+    ) -> Response | StreamingResponse | DeferredStreaming:
+        """Handle a provider-specific request.
+
+        Args:
+            request: FastAPI request object with endpoint and method in request.state.context
+
+        Returns:
+            Response, StreamingResponse, or DeferredStreaming object
+        """
+        ...
+
+    @abstractmethod
+    async def handle_streaming(
+        self, request: Request, endpoint: str, **kwargs: Any
+    ) -> StreamingResponse | DeferredStreaming:
+        """Handle a streaming request.
+
+        Args:
+            request: FastAPI request object
+            endpoint: Target endpoint path
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            StreamingResponse or DeferredStreaming object
+        """
+        ...
+
+    async def validate_request(
+        self, request: Request, endpoint: str
+    ) -> dict[str, Any] | None:
+        """Validate request before processing.
+
+        Args:
+            request: FastAPI request object
+            endpoint: Target endpoint path
+
+        Returns:
+            Validation result or None if valid
+        """
+        return None
+
+    async def transform_request(self, request_data: dict[str, Any]) -> dict[str, Any]:
+        """Transform request data if needed.
+
+        Args:
+            request_data: Original request data
+
+        Returns:
+            Transformed request data
+        """
+        return request_data
+
+    async def transform_response(self, response_data: dict[str, Any]) -> dict[str, Any]:
+        """Transform response data if needed.
+
+        Args:
+            response_data: Original response data
+
+        Returns:
+            Transformed response data
+        """
+        return response_data
+
+    def _ensure_tool_accumulator(self, request_context: Any) -> None:
+        """Attach tool accumulator metadata to the request context if available."""
+
+        if not self.tool_accumulator_class or not request_context:
+            return
+
+        if getattr(request_context, "_tool_accumulator_class", None) is None:
+            request_context._tool_accumulator_class = self.tool_accumulator_class
+
+    @staticmethod
+    def _record_tool_definitions(request_context: Any, payload: Any) -> None:
+        """Persist tool definitions on the request context for downstream consumers."""
+
+        if not request_context or not isinstance(payload, dict):
+            return
+
+        metadata = getattr(request_context, "metadata", None)
+        if not isinstance(metadata, dict):
+            return
+
+        tools = payload.get("tools")
+        if tools and "_tool_definitions" not in metadata:
+            metadata["_tool_definitions"] = tools
+
+    @abstractmethod
+    async def cleanup(self) -> None:
+        """Cleanup adapter resources.
+
+        This method should be overridden by concrete adapters to clean up
+        any resources like HTTP clients, sessions, or background tasks.
+        Called during application shutdown.
+        """
+        ...

ccproxy/services/adapters/chain_composer.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import contextlib
+from collections.abc import AsyncIterator
+from typing import Any, Literal
+
+from .format_adapter import DictFormatAdapter, FormatAdapterProtocol
+from .format_registry import FormatRegistry
+
+
+class ComposedAdapter(DictFormatAdapter):
+    """A DictFormatAdapter composed from multiple pairwise adapters."""
+
+    pass
+
+
+def _pairs_from_chain(
+    chain: list[str], stage: Literal["request", "response", "error", "stream"]
+) -> list[tuple[str, str]]:
+    if len(chain) < 2:
+        return []
+    # For responses and streaming, convert from provider format (tail) back to client format (head)
+    if stage in ("response", "error", "stream"):
+        pairs = [(chain[i + 1], chain[i]) for i in range(len(chain) - 1)]
+        pairs.reverse()
+        return pairs
+    # Requests go forward (client -> provider)
+    return [(chain[i], chain[i + 1]) for i in range(len(chain) - 1)]
+
+
+def compose_from_chain(
+    *,
+    registry: FormatRegistry,
+    chain: list[str],
+    name: str | None = None,
+) -> FormatAdapterProtocol:
+    """Compose a FormatAdapter from a format_chain using the registry.
+
+    The composed adapter sequentially applies the per‑pair adapters for request,
+    response, error, and stream stages.
+    """
+
+    async def _compose_stage(
+        data: dict[str, Any], stage: Literal["request", "response", "error"]
+    ) -> dict[str, Any]:
+        current = data
+        for src, dst in _pairs_from_chain(chain, stage):
+            adapter = registry.get(src, dst)
+            if stage == "request":
+                current = await adapter.convert_request(current)
+            elif stage == "response":
+                current = await adapter.convert_response(current)
+            else:
+                # Default error passthrough if adapter lacks explicit error handling
+                with contextlib.suppress(NotImplementedError):
+                    current = await adapter.convert_error(current)
+        return current
+
+    async def _request(data: dict[str, Any]) -> dict[str, Any]:
+        return await _compose_stage(data, "request")
+
+    async def _response(data: dict[str, Any]) -> dict[str, Any]:
+        return await _compose_stage(data, "response")
+
+    async def _error(data: dict[str, Any]) -> dict[str, Any]:
+        return await _compose_stage(data, "error")
+
+    async def _stream(
+        stream: AsyncIterator[dict[str, Any]],
+    ) -> AsyncIterator[dict[str, Any]]:
+        # Pipe the stream through each pairwise adapter's convert_stream
+        current_stream = stream
+        for src, dst in _pairs_from_chain(chain, "stream"):
+            adapter = registry.get(src, dst)
+            current_stream = adapter.convert_stream(current_stream)
+        async for item in current_stream:
+            yield item
+
+    return ComposedAdapter(
+        request=_request,
+        response=_response,
+        error=_error,
+        stream=_stream,
+        name=name or f"ComposedAdapter({' -> '.join(chain)})",
+    )
+
+
+__all__ = ["compose_from_chain", "ComposedAdapter"]

ccproxy/services/adapters/chain_validation.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .format_registry import FormatRegistry
+
+
+def validate_chains(
+    *, registry: FormatRegistry, chains: Iterable[list[str]]
+) -> list[str]:
+    """Validate that all adjacent pairs in chains exist in the registry.
+
+    Returns a list of human‑readable error strings for missing pairs.
+    """
+    errors: list[str] = []
+    pairs_needed: set[tuple[str, str]] = set()
+    for chain in chains:
+        if len(chain) >= 2:
+            for i in range(len(chain) - 1):
+                pairs_needed.add((chain[i], chain[i + 1]))
+    for src, dst in sorted(pairs_needed):
+        if registry.get_if_exists(src, dst) is None:
+            errors.append(f"Missing format adapter: {src} -> {dst}")
+    return errors
+
+
+def validate_stream_pairs(
+    *, registry: FormatRegistry, chains: Iterable[list[str]]
+) -> list[str]:
+    """Validate reverse-direction pairs for streaming (provider→client)."""
+    missing: list[str] = []
+    for chain in chains:
+        if len(chain) < 2:
+            continue
+        reverse_pairs = list(
+            reversed([(chain[i + 1], chain[i]) for i in range(len(chain) - 1)])
+        )
+        for src, dst in reverse_pairs:
+            if registry.get_if_exists(src, dst) is None:
+                missing.append(f"Missing streaming adapter: {src} -> {dst}")
+    return missing
+
+
+__all__ = ["validate_chains", "validate_stream_pairs"]

ccproxy/services/adapters/chat_accumulator.py

@@ -0,0 +1,200 @@
+"""ChatCompletion accumulator for OpenAI streaming format."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from .delta_utils import accumulate_delta
+
+
+class ChatCompletionAccumulator:
+    """Accumulator for OpenAI ChatCompletion streaming format.
+
+    Handles partial tool calls and other streaming data by accumulating
+    chunks until complete objects are ready for validation.
+
+    Follows the OpenAI SDK ChatCompletionStreamManager pattern.
+    """
+
+    def __init__(self) -> None:
+        self._accumulated: dict[str, Any] = {}
+        self._done_tool_calls: set[int] = set()
+        self._current_tool_call_index: int | None = None
+
+    def accumulate_chunk(self, chunk: dict[str, Any]) -> dict[str, Any] | None:
+        """Accumulate a streaming chunk and return complete object if ready.
+
+        Args:
+            chunk: The incoming stream chunk data
+
+        Returns:
+            None if accumulation is ongoing, or the complete object when ready
+            for validation
+        """
+        # For chunks without tool calls, return immediately UNLESS we have accumulated state
+        # (in which case this might be a finish_reason chunk)
+        if not self._has_tool_calls(chunk) and not self._accumulated:
+            return chunk
+
+        # For the first chunk, copy the base structure
+        if not self._accumulated:
+            self._accumulated = copy.deepcopy(chunk)
+        else:
+            # For subsequent chunks, preserve base fields and only accumulate deltas
+            base_fields = {"id", "object", "created", "model"}
+            chunk_copy = copy.deepcopy(chunk)
+
+            # Remove base fields from chunk_copy to avoid concatenation
+            for field in base_fields:
+                if field in chunk_copy:
+                    del chunk_copy[field]
+
+            # Use accumulate_delta for the remaining fields (choices, etc.)
+            self._accumulated = accumulate_delta(self._accumulated, chunk_copy)
+
+        # Track tool call progress if present
+        if self._has_tool_calls(chunk):
+            self._track_tool_call_progress(chunk)
+
+        # Don't validate if we have incomplete tool calls
+        if self._has_incomplete_tool_calls():
+            return None  # Continue accumulating
+
+        # Return a copy for validation if chunk seems complete
+        if self._should_emit_chunk(chunk):
+            return copy.deepcopy(self._accumulated)
+
+        # Continue accumulating
+        return None
+
+    def reset(self) -> None:
+        """Reset accumulator state for next message."""
+        self._accumulated.clear()
+        self._done_tool_calls.clear()
+        self._current_tool_call_index = None
+
+    def _has_tool_calls(self, chunk: dict[str, Any]) -> bool:
+        """Check if chunk contains tool call data."""
+        if not isinstance(chunk, dict) or "choices" not in chunk:
+            return False
+
+        for choice in chunk.get("choices", []):
+            if not isinstance(choice, dict):
+                continue
+            delta = choice.get("delta", {})
+            if isinstance(delta, dict) and "tool_calls" in delta:
+                return True
+
+        return False
+
+    def _track_tool_call_progress(self, chunk: dict[str, Any]) -> None:
+        """Track progress of tool calls in this chunk."""
+        for choice in chunk.get("choices", []):
+            if not isinstance(choice, dict):
+                continue
+
+            delta = choice.get("delta", {})
+            if not isinstance(delta, dict):
+                continue
+
+            tool_calls = delta.get("tool_calls", [])
+            if not isinstance(tool_calls, list):
+                continue
+
+            for tool_call in tool_calls:
+                if not isinstance(tool_call, dict):
+                    continue
+
+                # Track current tool call index
+                if "index" in tool_call:
+                    self._current_tool_call_index = tool_call["index"]
+
+                # Mark tool call as done if it has complete structure
+                if self._is_tool_call_complete(tool_call):
+                    index = tool_call.get("index", self._current_tool_call_index)
+                    if index is not None:
+                        self._done_tool_calls.add(index)
+
+    def _is_tool_call_complete(self, tool_call: dict[str, Any]) -> bool:
+        """Check if a tool call has all required fields."""
+        if not tool_call.get("id"):
+            return False
+
+        function = tool_call.get("function", {})
+        if not isinstance(function, dict):
+            return False
+
+        if not function.get("name"):
+            return False
+
+        # Arguments can be empty string, but should be present
+        return "arguments" in function
+
+    def _has_incomplete_tool_calls(self) -> bool:
+        """Check if accumulated state has incomplete tool calls."""
+        if not self._accumulated.get("choices"):
+            return False
+
+        for choice in self._accumulated["choices"]:
+            if not isinstance(choice, dict):
+                continue
+
+            delta = choice.get("delta", {})
+            if not isinstance(delta, dict):
+                continue
+
+            tool_calls = delta.get("tool_calls", [])
+            if not isinstance(tool_calls, list):
+                continue
+
+            for tool_call in tool_calls:
+                if not isinstance(tool_call, dict):
+                    continue
+
+                # Check if this tool call is incomplete
+                if not self._is_tool_call_complete(tool_call):
+                    return True
+
+        return False
+
+    def _should_emit_chunk(self, chunk: dict[str, Any]) -> bool:
+        """Determine if we should emit the accumulated chunk for validation.
+
+        We emit when:
+        1. No tool calls are present (regular content)
+        2. All tool calls in the accumulated state are complete AND we see a finish_reason
+        """
+        # If no tool calls in accumulated state, emit immediately
+        if not self._has_any_tool_calls_in_accumulated():
+            return True
+
+        # For tool calls, only emit when both conditions are met:
+        # 1. All tool calls are complete
+        # 2. We see a finish_reason (indicates end of tool call sequence)
+        has_finish_reason = False
+        for choice in chunk.get("choices", []):
+            if isinstance(choice, dict) and choice.get("finish_reason"):
+                has_finish_reason = True
+                break
+
+        return bool(has_finish_reason and not self._has_incomplete_tool_calls())
+
+    def _has_any_tool_calls_in_accumulated(self) -> bool:
+        """Check if accumulated state has any tool calls."""
+        if not self._accumulated.get("choices"):
+            return False
+
+        for choice in self._accumulated["choices"]:
+            if not isinstance(choice, dict):
+                continue
+
+            delta = choice.get("delta", {})
+            if not isinstance(delta, dict):
+                continue
+
+            tool_calls = delta.get("tool_calls", [])
+            if isinstance(tool_calls, list) and tool_calls:
+                return True
+
+        return False

ccproxy/services/adapters/delta_utils.py

@@ -0,0 +1,142 @@
+"""Delta accumulation utilities following OpenAI SDK patterns."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def accumulate_delta(
+    accumulated: dict[str, Any], delta: dict[str, Any]
+) -> dict[str, Any]:
+    """Recursively merge delta into accumulated following OpenAI's rules.
+
+    This function implements the same accumulation logic as OpenAI's SDK:
+    - Concatenate strings
+    - Add numbers (int/float)
+    - Recursively merge dictionaries
+    - Extend primitive lists
+    - Merge object lists by 'index' key
+    - Preserve 'index' and 'type' keys without modification
+
+    Args:
+        accumulated: The accumulated state to merge into
+        delta: The delta to merge
+
+    Returns:
+        The merged result (may modify accumulated in-place)
+
+    Raises:
+        TypeError: For unsupported data types
+        ValueError: For invalid list structures
+    """
+    # Handle None/empty cases
+    if not delta:
+        return accumulated
+    if not accumulated:
+        return dict(delta)
+
+    # Work on a copy to avoid mutating input
+    result = dict(accumulated)
+
+    for key, delta_value in delta.items():
+        if key not in result:
+            # New key, just set it
+            result[key] = delta_value
+            continue
+
+        current_value = result[key]
+
+        # Handle different data type combinations
+        if isinstance(current_value, str) and isinstance(delta_value, str):
+            # Concatenate strings
+            result[key] = current_value + delta_value
+
+        elif isinstance(current_value, int | float) and isinstance(
+            delta_value, int | float
+        ):
+            # Add numbers
+            result[key] = current_value + delta_value
+
+        elif isinstance(current_value, dict) and isinstance(delta_value, dict):
+            # Recursively merge dictionaries
+            result[key] = accumulate_delta(current_value, delta_value)
+
+        elif isinstance(current_value, list) and isinstance(delta_value, list):
+            # Handle list merging
+            result[key] = _accumulate_list(current_value, delta_value)
+
+        else:
+            # For any other case, delta value overwrites
+            result[key] = delta_value
+
+    return result
+
+
+def _accumulate_list(current: list[Any], delta: list[Any]) -> list[Any]:
+    """Accumulate list values following OpenAI's patterns.
+
+    - For primitive lists: extend
+    - For object lists: merge by 'index' key
+
+    Args:
+        current: Current list value
+        delta: Delta list value
+
+    Returns:
+        Merged list
+
+    Raises:
+        ValueError: If object list entries are missing required 'index' key
+    """
+    if not delta:
+        return current
+    if not current:
+        return list(delta)
+
+    # Check if this is an object list (contains dicts with 'index')
+    has_indexed_objects = any(
+        isinstance(item, dict) and "index" in item for item in (current + delta)
+    )
+
+    if not has_indexed_objects:
+        # Primitive list - just extend
+        return current + delta
+
+    # Object list - merge by index
+    result = list(current)
+
+    for delta_item in delta:
+        if not isinstance(delta_item, dict):
+            # Mixed list types - append non-dict items
+            result.append(delta_item)
+            continue
+
+        if "index" not in delta_item:
+            raise ValueError("Dictionary in list delta must have 'index' key")
+
+        delta_index = delta_item["index"]
+
+        # Find existing item with same index
+        existing_item = None
+        existing_pos = None
+        for i, item in enumerate(result):
+            if isinstance(item, dict) and item.get("index") == delta_index:
+                existing_item = item
+                existing_pos = i
+                break
+
+        if existing_item is not None and existing_pos is not None:
+            # Merge with existing item, preserving special keys
+            merged = accumulate_delta(existing_item, delta_item)
+
+            # Preserve 'index' and 'type' from original if not in delta
+            for special_key in ["index", "type"]:
+                if special_key not in delta_item and special_key in existing_item:
+                    merged[special_key] = existing_item[special_key]
+
+            result[existing_pos] = merged
+        else:
+            # New item - append to list
+            result.append(delta_item)
+
+    return result