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

llmconnector/openai_client.py

@@ -4,99 +4,164 @@ from __future__ import annotations
 
 import base64
 import mimetypes
-from pathlib import Path
-import logging
-from typing import Optional, Sequence, Union
-
-from openai import OpenAI
-
-try:
-    from openai import APIError as OpenAIError  # type: ignore
-except ImportError:  # pragma: no cover - fallback for older SDKs
-    from openai.error import OpenAIError  # type: ignore
-
-ImageInput = Union[str, Path]
-logger = logging.getLogger(__name__)
+from pathlib import Path
+import logging
+from typing import Optional, Sequence
+
+from openai import OpenAI
+
+from .types import ImageInput, MessageSequence, normalize_messages
+from .utils import clamp_retries, run_sync_in_thread, run_with_retries
+
+logger = logging.getLogger(__name__)
 
 
 class OpenAIResponsesClient:
     """Convenience wrapper around the OpenAI Responses API."""
 
-    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:
-        """Generate a response from the specified model.
-
-        Args:
-            api_key: Secret key used to authenticate with OpenAI.
-            prompt: Natural-language instruction or query for the model.
-            model: Identifier of the OpenAI model to target (for example, ``"gpt-4o"``).
-            max_tokens: Cap for tokens across the entire exchange, defaults to 32000.
-            reasoning_effort: Optional reasoning effort hint (``"low"``, ``"medium"``, or ``"high"``).
-            images: Optional collection of image references (local paths or URLs).
-
-        Returns:
-            The text output produced by the model.
-
+    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:
+        """Generate a response from the specified model.
+
+        Args:
+            api_key: Secret key used to authenticate with OpenAI.
+            prompt: Natural-language instruction or query for the model.
+            model: Identifier of the OpenAI model to target (for example, ``"gpt-4o"``).
+            max_tokens: Cap for tokens across the entire exchange, defaults to 32000.
+            reasoning_effort: Optional reasoning effort hint (``"low"``, ``"medium"``, or ``"high"``).
+            images: Optional collection of image references (local paths or URLs).
+            messages: Optional list of chat-style messages (role/content).
+            request_id: Optional request identifier for tracing/logging.
+            timeout_s: Optional request timeout in seconds.
+            max_retries: Optional retry count for transient failures.
+            retry_backoff_s: Base delay (seconds) for exponential backoff between retries.
+
+        Returns:
+            The text output produced by the model.
+
         Raises:
             ValueError: If required arguments are missing or the request payload is empty.
             OpenAIError: If the underlying OpenAI request fails.
-        """
-        if not api_key:
-            raise ValueError("api_key must be provided.")
-        if not prompt and not images:
-            raise ValueError("At least one of prompt or images must be provided.")
-        if not model:
-            raise ValueError("model must be provided.")
-
-        client = OpenAI(api_key=api_key)
-
-        content_blocks = []
-        if prompt:
-            content_blocks.append({"type": "input_text", "text": prompt})
-
-        if images:
-            for image in images:
-                content_blocks.append(self._to_image_block(image))
-
-        if not content_blocks:
-            raise ValueError("No content provided for response generation.")
-
-        request_payload = {
-            "model": model,
-            "input": [
-                {
-                    "role": "user",
-                    "content": content_blocks,
-                }
-            ],
-            "max_output_tokens": max_tokens,
-        }
-
-        if reasoning_effort:
-            request_payload["reasoning"] = {"effort": reasoning_effort}
-
-        try:
-            response = client.responses.create(**request_payload)
-        except Exception as exc:  # Log and re-raise to preserve default behavior
-            logger.exception("OpenAI Responses API request failed: %s", exc)
-            raise
-
-        output_text = response.output_text
-        logger.info(
-            "OpenAI generate_response succeeded: model=%s images=%d text_len=%d",
-            model,
-            len(images or []),
-            len(output_text or ""),
-        )
-        return output_text
+        """
+        if not api_key:
+            raise ValueError("api_key must be provided.")
+        if not prompt and not messages and not images:
+            raise ValueError("At least one of prompt, messages, or images must be provided.")
+        if not model:
+            raise ValueError("model must be provided.")
+
+        normalized_messages = normalize_messages(prompt=prompt, messages=messages)
+        content_messages: list[dict] = []
+        for message in normalized_messages:
+            content_blocks = []
+            if message["content"]:
+                content_blocks.append({"type": "input_text", "text": message["content"]})
+            content_messages.append({"role": message["role"], "content": content_blocks})
+
+        if images:
+            image_blocks = [self._to_image_block(image) for image in images]
+            target_index = next(
+                (
+                    index
+                    for index in range(len(content_messages) - 1, -1, -1)
+                    if content_messages[index]["role"] == "user"
+                ),
+                None,
+            )
+            if target_index is None:
+                content_messages.append({"role": "user", "content": image_blocks})
+            else:
+                content_messages[target_index]["content"].extend(image_blocks)
+
+        if not any(message["content"] for message in content_messages):
+            raise ValueError("No content provided for response generation.")
+
+        request_payload = {
+            "model": model,
+            "input": content_messages,
+            "max_output_tokens": max_tokens,
+        }
+
+        if reasoning_effort:
+            request_payload["reasoning"] = {"effort": reasoning_effort}
+
+        retry_count = clamp_retries(max_retries)
+
+        def _run_request() -> str:
+            client_kwargs = {"api_key": api_key}
+            if timeout_s is not None:
+                client_kwargs["timeout"] = timeout_s
+            client = OpenAI(**client_kwargs)
+            try:
+                response = client.responses.create(**request_payload)
+            except Exception as exc:  # Log and re-raise to preserve default behavior
+                logger.exception(
+                    "OpenAI Responses API request failed: %s request_id=%s",
+                    exc,
+                    request_id,
+                )
+                raise
+
+            output_text = response.output_text
+            logger.info(
+                "OpenAI generate_response succeeded: model=%s images=%d text_len=%d request_id=%s",
+                model,
+                len(images or []),
+                len(output_text or ""),
+                request_id,
+            )
+            return output_text
+
+        return run_with_retries(
+            func=_run_request,
+            max_retries=retry_count,
+            retry_backoff_s=retry_backoff_s,
+            request_id=request_id,
+        )
+
+    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:
+        return await run_sync_in_thread(
+            lambda: self.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,
+            )
+        )
 
     @staticmethod
     def _to_image_block(image: ImageInput) -> dict:
@@ -118,51 +183,119 @@ class OpenAIResponsesClient:
             "image_url": _encode_image_path(Path(image)),
         }
 
-    def generate_image(
-        self,
-        *,
-        api_key: str,
-        prompt: str,
+    def generate_image(
+        self,
+        *,
+        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 OpenAI API.
 
-        Raises:
-            NotImplementedError: This method is not yet implemented for OpenAI.
-        """
-        raise NotImplementedError("Image generation is not implemented for OpenAI.")
-
-    def list_models(self, *, api_key: str) -> list[dict[str, Optional[str]]]:
-        """Return the models available to the authenticated OpenAI account."""
-        if not api_key:
-            raise ValueError("api_key must be provided.")
-
-        client = OpenAI(api_key=api_key)
-        try:
-            response = client.models.list()
-        except Exception as exc:
-            logger.exception("OpenAI list models failed: %s", exc)
-            raise
-        data = getattr(response, "data", []) or []
-
-        models: list[dict[str, Optional[str]]] = []
-        for model in data:
-            model_id = getattr(model, "id", None)
-            if model_id is None and isinstance(model, dict):
-                model_id = model.get("id")
-            if not model_id:
-                continue
-
-            display_name = getattr(model, "display_name", None)
-            if display_name is None and isinstance(model, dict):
-                display_name = model.get("display_name")
-
-            models.append({"id": model_id, "display_name": display_name})
-
-        logger.info("OpenAI list_models succeeded: count=%d", len(models))
-        return models
+        Raises:
+            NotImplementedError: This method is not yet implemented for OpenAI.
+        """
+        raise NotImplementedError("Image generation is not implemented for OpenAI.")
+
+    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:
+        return await run_sync_in_thread(
+            lambda: self.generate_image(
+                api_key=api_key,
+                prompt=prompt,
+                model=model,
+                image_size=image_size,
+                aspect_ratio=aspect_ratio,
+                image=image,
+            )
+        )
+
+    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,
+    ) -> list[dict[str, Optional[str]]]:
+        """Return the models available to the authenticated OpenAI account."""
+        if not api_key:
+            raise ValueError("api_key must be provided.")
+
+        retry_count = clamp_retries(max_retries)
+
+        def _run_request() -> list[dict[str, Optional[str]]]:
+            client_kwargs = {"api_key": api_key}
+            if timeout_s is not None:
+                client_kwargs["timeout"] = timeout_s
+            client = OpenAI(**client_kwargs)
+            try:
+                response = client.models.list()
+            except Exception as exc:
+                logger.exception(
+                    "OpenAI list models failed: %s request_id=%s", exc, request_id
+                )
+                raise
+            data = getattr(response, "data", []) or []
+
+            models: list[dict[str, Optional[str]]] = []
+            for model in data:
+                model_id = getattr(model, "id", None)
+                if model_id is None and isinstance(model, dict):
+                    model_id = model.get("id")
+                if not model_id:
+                    continue
+
+                display_name = getattr(model, "display_name", None)
+                if display_name is None and isinstance(model, dict):
+                    display_name = model.get("display_name")
+
+                models.append({"id": model_id, "display_name": display_name})
+
+            logger.info(
+                "OpenAI list_models succeeded: count=%d request_id=%s",
+                len(models),
+                request_id,
+            )
+            return models
+
+        return run_with_retries(
+            func=_run_request,
+            max_retries=retry_count,
+            retry_backoff_s=retry_backoff_s,
+            request_id=request_id,
+        )
+
+    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,
+    ) -> list[dict[str, Optional[str]]]:
+        return await run_sync_in_thread(
+            lambda: self.list_models(
+                api_key=api_key,
+                request_id=request_id,
+                timeout_s=timeout_s,
+                max_retries=max_retries,
+                retry_backoff_s=retry_backoff_s,
+            )
+        )
 
 
 def _encode_image_path(path: Path) -> str:

llmconnector/types.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Sequence, TypedDict, Union
+
+ImageInput = Union[str, Path]
+
+
+class Message(TypedDict):
+    role: str
+    content: str
+
+
+MessageSequence = Sequence[Message]
+
+
+class RequestOptions(TypedDict, total=False):
+    request_id: str
+    timeout_s: float
+    max_retries: int
+    retry_backoff_s: float
+    reasoning_effort: str
+    max_tokens: int
+    images: Sequence[ImageInput]
+    messages: MessageSequence
+
+
+def normalize_messages(
+    *,
+    prompt: Optional[str],
+    messages: Optional[MessageSequence],
+) -> list[Message]:
+    result: list[Message] = []
+    if messages:
+        for message in messages:
+            role = message.get("role")
+            content = message.get("content")
+            if not isinstance(role, str) or not role:
+                raise ValueError("message role must be a non-empty string")
+            if content is None:
+                content = ""
+            if not isinstance(content, str):
+                raise ValueError("message content must be a string")
+            result.append({"role": role, "content": content})
+
+    if prompt:
+        result.append({"role": "user", "content": prompt})
+
+    return result

llmconnector/utils.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Awaitable, Callable, TypeVar
+
+T = TypeVar("T")
+logger = logging.getLogger(__name__)
+
+
+def clamp_retries(max_retries: int | None) -> int:
+    if max_retries is None:
+        return 0
+    if max_retries < 0:
+        return 0
+    return max_retries
+
+
+def compute_delay(attempt: int, retry_backoff_s: float) -> float:
+    return retry_backoff_s * (2**attempt)
+
+
+def run_with_retries(
+    *,
+    func: Callable[[], T],
+    max_retries: int,
+    retry_backoff_s: float,
+    request_id: str | None = None,
+) -> T:
+    attempt = 0
+    while True:
+        try:
+            return func()
+        except Exception as exc:
+            if attempt >= max_retries:
+                raise
+            delay = compute_delay(attempt, retry_backoff_s)
+            logger.warning(
+                "Retrying LLM request: attempt=%d delay=%.2fs request_id=%s error=%s",
+                attempt + 1,
+                delay,
+                request_id,
+                exc,
+            )
+            time.sleep(delay)
+            attempt += 1
+
+
+async def run_with_retries_async(
+    *,
+    func: Callable[[], Awaitable[T]],
+    max_retries: int,
+    retry_backoff_s: float,
+    request_id: str | None = None,
+) -> T:
+    attempt = 0
+    while True:
+        try:
+            return await func()
+        except Exception as exc:
+            if attempt >= max_retries:
+                raise
+            delay = compute_delay(attempt, retry_backoff_s)
+            logger.warning(
+                "Retrying LLM request (async): attempt=%d delay=%.2fs request_id=%s error=%s",
+                attempt + 1,
+                delay,
+                request_id,
+                exc,
+            )
+            await asyncio.sleep(delay)
+            attempt += 1
+
+
+async def run_sync_in_thread(func: Callable[[], T]) -> T:
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, func)

ccs_llmconnector-1.0.5.dist-info/RECORD

@@ -1,14 +0,0 @@
-ccs_llmconnector-1.0.5.dist-info/licenses/LICENSE,sha256=rPcz2YmBB9VUWZTLJcRO_B4jKDpqmGRYi2eSI-unysg,1083
-llmconnector/__init__.py,sha256=RIprtUKqu2SrUmPJ8C7lPpCpvknpJqd93CUyxcaXy1I,1213
-llmconnector/anthropic_client.py,sha256=sBcJVmYbqTWeT_twcpDz-00XTreLjZlJ1ifVE4ik5TM,7889
-llmconnector/client.py,sha256=RUonlBnUX9EmhpGPUYAIksQyFmX0-rRGvYFsSZgrkQE,6111
-llmconnector/client_cli.py,sha256=cxu2NKix-9axNeY5jbfqR5rKPKJ-oqBSnJCY8PKMhYY,10660
-llmconnector/gemini_client.py,sha256=GgnsGizz_M2BMp_GLZpGXyVhzk_eI835zvyYrFnbaLM,10699
-llmconnector/grok_client.py,sha256=SXcufcsrYDQgx0tK7EOfIBybTZlEdhZc0MV6siUHyyQ,6453
-llmconnector/openai_client.py,sha256=6CzvRdzPP75XzXjQf6I_mUxsB2XFuEi2qJgcABMsCxI,5938
-llmconnector/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-ccs_llmconnector-1.0.5.dist-info/METADATA,sha256=WYx6wF-v8zmiC8LbUp9s7CJkSpXt1JiAOecAbk40xfw,14957
-ccs_llmconnector-1.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ccs_llmconnector-1.0.5.dist-info/entry_points.txt,sha256=eFvLY3nHAG_QhaKlemhhK7echfezW0KiMdSNMZOStLc,60
-ccs_llmconnector-1.0.5.dist-info/top_level.txt,sha256=Doer7TAUsN8UXQfPHPNsuBXVNCz2uV-Q0v4t4fwv_MM,13
-ccs_llmconnector-1.0.5.dist-info/RECORD,,