ccs-llmconnector 1.0.5__py3-none-any.whl → 1.1.0__py3-none-any.whl

llmconnector/client.py

@@ -2,43 +2,95 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import TYPE_CHECKING, Dict, Optional, Protocol, Sequence, Union
-
-if TYPE_CHECKING:
-    from .openai_client import ImageInput, OpenAIResponsesClient
-else:
-    ImageInput = Union[str, Path]
-
-
-class SupportsGenerateResponse(Protocol):
-    """Protocol describing provider clients."""
-
-    def generate_response(
-        self,
-        *,
-        api_key: str,
-        prompt: str,
-        model: str,
-        max_tokens: int = 32000,
-        reasoning_effort: Optional[str] = None,
-        images: Optional[Sequence[ImageInput]] = None,
-    ) -> str:
-        ...
-
-    def generate_image(
-        self,
-        *,
-        api_key: str,
-        prompt: str,
+import asyncio
+from typing import Dict, Optional, Protocol, Sequence
+
+from .types import ImageInput, MessageSequence
+from .utils import run_sync_in_thread
+
+
+class SupportsGenerateResponse(Protocol):
+    """Protocol describing provider clients."""
+
+    def generate_response(
+        self,
+        *,
+        api_key: str,
+        prompt: Optional[str] = None,
+        model: str,
+        max_tokens: int = 32000,
+        reasoning_effort: Optional[str] = None,
+        images: Optional[Sequence[ImageInput]] = None,
+        messages: Optional[MessageSequence] = None,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> str:
+        ...
+
+    async def async_generate_response(
+        self,
+        *,
+        api_key: str,
+        prompt: Optional[str] = None,
+        model: str,
+        max_tokens: int = 32000,
+        reasoning_effort: Optional[str] = None,
+        images: Optional[Sequence[ImageInput]] = None,
+        messages: Optional[MessageSequence] = None,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> str:
+        ...
+
+    def generate_image(
+        self,
+        *,
+        api_key: str,
+        prompt: str,
         model: str,
-        image_size: str = "2K",
-        image: Optional[ImageInput] = None,
-    ) -> bytes:
-        ...
-
-    def list_models(self, *, api_key: str) -> Sequence[dict[str, Optional[str]]]:
-        ...
+        image_size: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
+        image: Optional[ImageInput] = None,
+    ) -> bytes:
+        ...
+
+    async def async_generate_image(
+        self,
+        *,
+        api_key: str,
+        prompt: str,
+        model: str,
+        image_size: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
+        image: Optional[ImageInput] = None,
+    ) -> bytes:
+        ...
+
+    def list_models(
+        self,
+        *,
+        api_key: str,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> Sequence[dict[str, Optional[str]]]:
+        ...
+
+    async def async_list_models(
+        self,
+        *,
+        api_key: str,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> Sequence[dict[str, Optional[str]]]:
+        ...
 
 
 class LLMClient:
@@ -68,17 +120,22 @@ class LLMClient:
 
         self._providers[name.lower()] = client
 
-    def generate_response(
-        self,
-        *,
-        provider: str,
-        api_key: str,
-        prompt: str,
-        model: str,
-        max_tokens: int = 32000,
-        reasoning_effort: Optional[str] = None,
-        images: Optional[Sequence[ImageInput]] = None,
-    ) -> str:
+    def generate_response(
+        self,
+        *,
+        provider: str,
+        api_key: str,
+        prompt: Optional[str] = None,
+        model: str,
+        max_tokens: int = 32000,
+        reasoning_effort: Optional[str] = None,
+        images: Optional[Sequence[ImageInput]] = None,
+        messages: Optional[MessageSequence] = None,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> str:
         """Generate a response using the selected provider."""
         if not provider:
             raise ValueError("provider must be provided.")
@@ -90,23 +147,88 @@ class LLMClient:
                 f"Unknown provider '{provider}'. Available providers: {available}."
             )
 
-        return provider_client.generate_response(
-            api_key=api_key,
-            prompt=prompt,
-            model=model,
-            max_tokens=max_tokens,
-            reasoning_effort=reasoning_effort,
-            images=images,
-        )
+        return provider_client.generate_response(
+            api_key=api_key,
+            prompt=prompt,
+            model=model,
+            max_tokens=max_tokens,
+            reasoning_effort=reasoning_effort,
+            images=images,
+            messages=messages,
+            request_id=request_id,
+            timeout_s=timeout_s,
+            max_retries=max_retries,
+            retry_backoff_s=retry_backoff_s,
+        )
+
+    async def async_generate_response(
+        self,
+        *,
+        provider: str,
+        api_key: str,
+        prompt: Optional[str] = None,
+        model: str,
+        max_tokens: int = 32000,
+        reasoning_effort: Optional[str] = None,
+        images: Optional[Sequence[ImageInput]] = None,
+        messages: Optional[MessageSequence] = None,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> str:
+        """Generate a response using the selected provider (async)."""
+        if not provider:
+            raise ValueError("provider must be provided.")
+
+        provider_client = self._providers.get(provider.lower())
+        if provider_client is None:
+            available = ", ".join(sorted(self._providers)) or "<none>"
+            raise ValueError(
+                f"Unknown provider '{provider}'. Available providers: {available}."
+            )
+
+        async_method = getattr(provider_client, "async_generate_response", None)
+        if async_method is not None and asyncio.iscoroutinefunction(async_method):
+            return await async_method(
+                api_key=api_key,
+                prompt=prompt,
+                model=model,
+                max_tokens=max_tokens,
+                reasoning_effort=reasoning_effort,
+                images=images,
+                messages=messages,
+                request_id=request_id,
+                timeout_s=timeout_s,
+                max_retries=max_retries,
+                retry_backoff_s=retry_backoff_s,
+            )
+
+        return await run_sync_in_thread(
+            lambda: provider_client.generate_response(
+                api_key=api_key,
+                prompt=prompt,
+                model=model,
+                max_tokens=max_tokens,
+                reasoning_effort=reasoning_effort,
+                images=images,
+                messages=messages,
+                request_id=request_id,
+                timeout_s=timeout_s,
+                max_retries=max_retries,
+                retry_backoff_s=retry_backoff_s,
+            )
+        )
 
-    def generate_image(
-        self,
-        *,
-        provider: str,
-        api_key: str,
+    def generate_image(
+        self,
+        *,
+        provider: str,
+        api_key: str,
         prompt: str,
         model: str,
-        image_size: str = "2K",
+        image_size: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
         image: Optional[ImageInput] = None,
     ) -> bytes:
         """Generate an image using the selected provider."""
@@ -120,20 +242,69 @@ class LLMClient:
                 f"Unknown provider '{provider}'. Available providers: {available}."
             )
 
-        return provider_client.generate_image(
-            api_key=api_key,
-            prompt=prompt,
-            model=model,
-            image_size=image_size,
-            image=image,
-        )
+        return provider_client.generate_image(
+            api_key=api_key,
+            prompt=prompt,
+            model=model,
+            image_size=image_size,
+            aspect_ratio=aspect_ratio,
+            image=image,
+        )
+
+    async def async_generate_image(
+        self,
+        *,
+        provider: str,
+        api_key: str,
+        prompt: str,
+        model: str,
+        image_size: Optional[str] = None,
+        aspect_ratio: Optional[str] = None,
+        image: Optional[ImageInput] = None,
+    ) -> bytes:
+        """Generate an image using the selected provider (async)."""
+        if not provider:
+            raise ValueError("provider must be provided.")
+
+        provider_client = self._providers.get(provider.lower())
+        if provider_client is None:
+            available = ", ".join(sorted(self._providers)) or "<none>"
+            raise ValueError(
+                f"Unknown provider '{provider}'. Available providers: {available}."
+            )
+
+        async_method = getattr(provider_client, "async_generate_image", None)
+        if async_method is not None and asyncio.iscoroutinefunction(async_method):
+            return await async_method(
+                api_key=api_key,
+                prompt=prompt,
+                model=model,
+                image_size=image_size,
+                aspect_ratio=aspect_ratio,
+                image=image,
+            )
+
+        return await run_sync_in_thread(
+            lambda: provider_client.generate_image(
+                api_key=api_key,
+                prompt=prompt,
+                model=model,
+                image_size=image_size,
+                aspect_ratio=aspect_ratio,
+                image=image,
+            )
+        )
 
-    def list_models(
-        self,
-        *,
-        provider: str,
-        api_key: str,
-    ) -> Sequence[dict[str, Optional[str]]]:
+    def list_models(
+        self,
+        *,
+        provider: str,
+        api_key: str,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> Sequence[dict[str, Optional[str]]]:
         """List models available for the specified provider."""
         if not provider:
             raise ValueError("provider must be provided.")
@@ -145,7 +316,54 @@ class LLMClient:
                 f"Unknown provider '{provider}'. Available providers: {available}."
             )
 
-        return provider_client.list_models(api_key=api_key)
+        return provider_client.list_models(
+            api_key=api_key,
+            request_id=request_id,
+            timeout_s=timeout_s,
+            max_retries=max_retries,
+            retry_backoff_s=retry_backoff_s,
+        )
+
+    async def async_list_models(
+        self,
+        *,
+        provider: str,
+        api_key: str,
+        request_id: Optional[str] = None,
+        timeout_s: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_backoff_s: float = 0.5,
+    ) -> Sequence[dict[str, Optional[str]]]:
+        """List models available for the specified provider (async)."""
+        if not provider:
+            raise ValueError("provider must be provided.")
+
+        provider_client = self._providers.get(provider.lower())
+        if provider_client is None:
+            available = ", ".join(sorted(self._providers)) or "<none>"
+            raise ValueError(
+                f"Unknown provider '{provider}'. Available providers: {available}."
+            )
+
+        async_method = getattr(provider_client, "async_list_models", None)
+        if async_method is not None and asyncio.iscoroutinefunction(async_method):
+            return await async_method(
+                api_key=api_key,
+                request_id=request_id,
+                timeout_s=timeout_s,
+                max_retries=max_retries,
+                retry_backoff_s=retry_backoff_s,
+            )
+
+        return await run_sync_in_thread(
+            lambda: provider_client.list_models(
+                api_key=api_key,
+                request_id=request_id,
+                timeout_s=timeout_s,
+                max_retries=max_retries,
+                retry_backoff_s=retry_backoff_s,
+            )
+        )
 
     @staticmethod
     def _discover_default_providers() -> Dict[str, SupportsGenerateResponse]:

llmconnector/client_cli.py

@@ -82,12 +82,35 @@ def _build_parser() -> argparse.ArgumentParser:
         default=32000,
         help="Maximum output tokens (provider-specific meaning)",
     )
-    p_respond.add_argument(
-        "--reasoning-effort",
-        choices=["low", "medium", "high"],
-        default=None,
-        help="Optional reasoning effort hint if supported",
-    )
+    p_respond.add_argument(
+        "--reasoning-effort",
+        choices=["low", "medium", "high"],
+        default=None,
+        help="Optional reasoning effort hint if supported",
+    )
+    p_respond.add_argument(
+        "--request-id",
+        default=None,
+        help="Optional request identifier for tracing/logging",
+    )
+    p_respond.add_argument(
+        "--timeout-s",
+        type=float,
+        default=None,
+        help="Optional timeout in seconds",
+    )
+    p_respond.add_argument(
+        "--max-retries",
+        type=int,
+        default=0,
+        help="Number of retries for transient failures",
+    )
+    p_respond.add_argument(
+        "--retry-backoff-s",
+        type=float,
+        default=0.5,
+        help="Base delay in seconds for exponential backoff",
+    )
 
     # models: list available models
     p_models = subparsers.add_parser(
@@ -149,15 +172,19 @@ def _cmd_respond(args: argparse.Namespace) -> int:
             print("Error: provide a prompt or at least one image.", file=sys.stderr)
             return 2
     try:
-        output = client.generate_response(
-            provider=provider,
-            api_key=api_key,
-            prompt=prompt,
-            model=model,
-            max_tokens=args.max_tokens,
-            reasoning_effort=args.reasoning_effort,
-            images=images,
-        )
+        output = client.generate_response(
+            provider=provider,
+            api_key=api_key,
+            prompt=prompt,
+            model=model,
+            max_tokens=args.max_tokens,
+            reasoning_effort=args.reasoning_effort,
+            images=images,
+            request_id=args.request_id,
+            timeout_s=args.timeout_s,
+            max_retries=args.max_retries,
+            retry_backoff_s=args.retry_backoff_s,
+        )
     except Exception as exc:  # pragma: no cover - CLI surface
         print(f"Error: {exc}", file=sys.stderr)
         return 2