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

ccproxy/services/adapters/format_adapter.py

@@ -0,0 +1,136 @@
+"""Format adapter interfaces and helpers for dict-based conversions."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+
+FormatDict = dict[str, Any]
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Await coroutine-like values produced by adapter callables."""
+
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+@runtime_checkable
+class FormatAdapterProtocol(Protocol):
+    """Protocol for format adapters operating on plain dictionaries."""
+
+    async def convert_request(self, data: FormatDict) -> FormatDict:
+        """Convert an outgoing request payload."""
+
+    async def convert_response(self, data: FormatDict) -> FormatDict:
+        """Convert a non-streaming response payload."""
+
+    async def convert_error(self, data: FormatDict) -> FormatDict:
+        """Convert an error payload."""
+
+    def convert_stream(
+        self, stream: AsyncIterator[FormatDict]
+    ) -> AsyncIterator[FormatDict]:
+        """Convert a streaming response represented as an async iterator."""
+
+
+class DictFormatAdapter(FormatAdapterProtocol):
+    """Adapter built from per-stage callables with strict dict IO."""
+
+    def __init__(
+        self,
+        *,
+        request: Callable[[FormatDict], Awaitable[FormatDict]]
+        | Callable[[FormatDict], FormatDict]
+        | None = None,
+        response: Callable[[FormatDict], Awaitable[FormatDict]]
+        | Callable[[FormatDict], FormatDict]
+        | None = None,
+        error: Callable[[FormatDict], Awaitable[FormatDict]]
+        | Callable[[FormatDict], FormatDict]
+        | None = None,
+        stream: Callable[[AsyncIterator[FormatDict]], AsyncIterator[FormatDict]]
+        | Callable[[AsyncIterator[FormatDict]], Awaitable[AsyncIterator[FormatDict]]]
+        | Callable[[AsyncIterator[FormatDict]], Awaitable[Any]]
+        | None = None,
+        name: str | None = None,
+    ) -> None:
+        self._request = request
+        self._response = response
+        self._error = error
+        self._stream = stream
+        self.name = name or self.__class__.__name__
+
+    async def convert_request(self, data: FormatDict) -> FormatDict:
+        return await self._run_stage(self._request, data, stage="request")
+
+    async def convert_response(self, data: FormatDict) -> FormatDict:
+        return await self._run_stage(self._response, data, stage="response")
+
+    async def convert_error(self, data: FormatDict) -> FormatDict:
+        return await self._run_stage(self._error, data, stage="error")
+
+    def convert_stream(
+        self, stream: AsyncIterator[FormatDict]
+    ) -> AsyncIterator[FormatDict]:
+        if self._stream is None:
+            raise NotImplementedError(
+                f"{self.name} does not implement stream conversion"
+            )
+
+        return self._create_stream_iterator(stream)
+
+    async def _create_stream_iterator(
+        self, stream: AsyncIterator[FormatDict]
+    ) -> AsyncIterator[FormatDict]:
+        """Helper method to create the actual async iterator."""
+        if self._stream is None:
+            raise NotImplementedError(
+                f"{self.name} does not implement stream conversion"
+            )
+
+        handler = self._stream(stream)
+        handler = await _maybe_await(handler)
+
+        if not hasattr(handler, "__aiter__"):
+            raise TypeError(
+                f"{self.name}.stream must return an async iterator, got {type(handler).__name__}"
+            )
+
+        async for item in handler:
+            if not isinstance(item, dict):
+                raise TypeError(
+                    f"{self.name}.stream yielded non-dict item: {type(item).__name__}"
+                )
+            yield item
+
+    async def _run_stage(
+        self,
+        func: Callable[[FormatDict], Awaitable[FormatDict]]
+        | Callable[[FormatDict], FormatDict]
+        | None,
+        data: FormatDict,
+        *,
+        stage: str,
+    ) -> FormatDict:
+        if func is None:
+            raise NotImplementedError(
+                f"{self.name} does not implement {stage} conversion"
+            )
+
+        result = await _maybe_await(func(data))
+        if not isinstance(result, dict):
+            raise TypeError(
+                f"{self.name}.{stage} must return dict, got {type(result).__name__}"
+            )
+        return result
+
+
+__all__ = [
+    "FormatAdapterProtocol",
+    "FormatDict",
+    "DictFormatAdapter",
+]

ccproxy/services/adapters/format_context.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FormatContext:
+    """Format conversion context for handler configuration."""
+
+    source_format: str | None = None
+    target_format: str | None = None
+    conversion_needed: bool = False
+    streaming_mode: str | None = None  # "auto", "force", "never"

ccproxy/services/adapters/format_registry.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING
+
+import structlog
+
+from ccproxy.services.adapters.format_adapter import FormatAdapterProtocol
+
+
+if TYPE_CHECKING:
+    from ccproxy.core.plugins import (
+        PluginManifest,
+    )
+
+logger = structlog.get_logger(__name__)
+
+
+class FormatRegistry:
+    """Registry mapping format pairs to concrete adapters."""
+
+    def __init__(self) -> None:
+        self._adapters: dict[tuple[str, str], FormatAdapterProtocol] = {}
+        self._registered_plugins: dict[tuple[str, str], str] = {}
+        self._pending_logs: dict[str, list[dict[str, str]]] = {}
+        self._current_batch_plugin: str | None = None
+
+    def register(
+        self,
+        *,
+        from_format: str,
+        to_format: str,
+        adapter: FormatAdapterProtocol,
+        plugin_name: str = "unknown",
+    ) -> None:
+        key = (from_format, to_format)
+        if key in self._adapters:
+            existing = self._registered_plugins[key]
+            logger.debug(
+                "format_adapter_duplicate_ignored",
+                from_format=from_format,
+                to_format=to_format,
+                existing_plugin=existing,
+                attempted_plugin=plugin_name,
+                category="format",
+            )
+            return
+
+        self._adapters[key] = adapter
+        self._registered_plugins[key] = plugin_name
+
+        if self._current_batch_plugin is None:
+            self._current_batch_plugin = plugin_name
+        elif self._current_batch_plugin != plugin_name:
+            self._flush_plugin_logs(self._current_batch_plugin)
+            self._current_batch_plugin = plugin_name
+
+        entries = self._pending_logs.setdefault(plugin_name, [])
+        entries.append(
+            {
+                "from_format": from_format,
+                "to_format": to_format,
+                "adapter_type": type(adapter).__name__,
+            }
+        )
+
+    def get(self, from_format: str, to_format: str) -> FormatAdapterProtocol:
+        if not from_format or not to_format:
+            raise ValueError("Format names cannot be empty")
+
+        key = (from_format, to_format)
+        adapter = self._adapters.get(key)
+        if adapter is None:
+            available = ", ".join(
+                f"{src}->{dst}" for src, dst in sorted(self._adapters)
+            )
+            raise ValueError(
+                f"No adapter registered for {from_format}->{to_format}. Available: {available}"
+            )
+        return adapter
+
+    def get_if_exists(
+        self, from_format: str, to_format: str
+    ) -> FormatAdapterProtocol | None:
+        if not from_format or not to_format:
+            raise ValueError("Format names cannot be empty")
+        return self._adapters.get((from_format, to_format))
+
+    def list_pairs(self) -> list[str]:
+        return [f"{src}->{dst}" for src, dst in sorted(self._adapters)]
+
+    def get_registered_plugins(self) -> set[str]:
+        return set(self._registered_plugins.values())
+
+    def clear(self) -> None:
+        self._adapters.clear()
+        self._registered_plugins.clear()
+        self._pending_logs.clear()
+        self._current_batch_plugin = None
+
+    async def register_from_manifest(
+        self, manifest: PluginManifest, plugin_name: str
+    ) -> None:
+        for spec in manifest.format_adapters:
+            adapter = spec.adapter_factory()
+            if inspect.isawaitable(adapter):
+                adapter = await adapter
+            if not isinstance(adapter, FormatAdapterProtocol):
+                raise TypeError(
+                    f"Adapter factory for {spec.from_format}->{spec.to_format} returned invalid type {adapter!r}"
+                )
+
+            self.register(
+                from_format=spec.from_format,
+                to_format=spec.to_format,
+                adapter=adapter,
+                plugin_name=plugin_name,
+            )
+        self._flush_plugin_logs(plugin_name)
+
+    def flush_all_logs(self) -> None:
+        if self._current_batch_plugin is not None:
+            self._flush_plugin_logs(self._current_batch_plugin)
+            self._current_batch_plugin = None
+
+        for plugin_name in list(self._pending_logs.keys()):
+            self._flush_plugin_logs(plugin_name)
+
+    def _flush_plugin_logs(self, plugin_name: str) -> None:
+        entries = self._pending_logs.get(plugin_name)
+        if not entries:
+            return
+
+        logger.debug(
+            "format_adapters_registered",
+            plugin=plugin_name,
+            count=len(entries),
+            entries=[entry.copy() for entry in entries],
+            category="format",
+        )
+        self._pending_logs.pop(plugin_name, None)
+        if self._current_batch_plugin == plugin_name:
+            self._current_batch_plugin = None
+
+    def validate_requirements(
+        self, manifests: dict[str, PluginManifest]
+    ) -> dict[str, list[tuple[str, str]]]:
+        available = set(self._adapters.keys())
+        missing: dict[str, list[tuple[str, str]]] = {}
+        for name, manifest in manifests.items():
+            required = manifest.requires_format_adapters
+            unresolved = [pair for pair in required if pair not in available]
+            if unresolved:
+                missing[name] = unresolved
+        return missing
+
+
+__all__ = ["FormatRegistry"]