ccs-llmconnector 1.0.6__py3-none-any.whl → 1.1.1__py3-none-any.whl

{ccs_llmconnector-1.0.6.dist-info → ccs_llmconnector-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccs-llmconnector
-Version: 1.0.6
+Version: 1.1.1
 Summary: Lightweight wrapper around different LLM provider Python SDK Responses APIs.
 Author: CCS
 License: MIT
@@ -9,9 +9,16 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: openai>=1.0.0
-Requires-Dist: google-genai
-Requires-Dist: anthropic
-Requires-Dist: xai-sdk
+Provides-Extra: gemini
+Requires-Dist: google-genai; extra == "gemini"
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+Provides-Extra: xai
+Requires-Dist: xai-sdk; extra == "xai"
+Provides-Extra: all
+Requires-Dist: google-genai; extra == "all"
+Requires-Dist: anthropic; extra == "all"
+Requires-Dist: xai-sdk; extra == "all"
 Dynamic: license-file
 
 # ccs-llmconnector
@@ -29,16 +36,24 @@ the models available to your account with each provider.
 # from PyPI (normalized project name)
 pip install ccs-llmconnector
 
+# install additional providers
+pip install "ccs-llmconnector[gemini]"
+pip install "ccs-llmconnector[anthropic]"
+pip install "ccs-llmconnector[xai]"
+pip install "ccs-llmconnector[all]"
+
 # or from source (this repository)
 pip install .
 ```
 
 ### Requirements
 
-- `openai` (installed automatically with the package)
-- `google-genai` (installed automatically with the package)
-- `anthropic` (installed automatically with the package)
-- `xai-sdk` (installed automatically with the package; requires Python 3.10+)
+- `openai` (installed automatically with the base package)
+- Optional extras:
+  - `ccs-llmconnector[gemini]` -> `google-genai`
+  - `ccs-llmconnector[anthropic]` -> `anthropic`
+  - `ccs-llmconnector[xai]` -> `xai-sdk` (Python 3.10+)
+  - `ccs-llmconnector[all]` -> all providers
 
 ## Components
 
@@ -48,6 +63,17 @@ pip install .
 - `GrokClient` - wrapper around the xAI Grok chat API, usable when `xai-sdk` is installed. Includes a model discovery helper.
 - `LLMClient` - provider router that delegates to registered clients (OpenAI included by default) so additional vendors can be added without changing call sites.
 
+## Common Options
+
+All clients expose the same optional controls:
+
+- `messages`: list of `{role, content}` entries (e.g., `system`, `user`, `assistant`). If both `prompt` and `messages` are provided, `prompt` is appended as the last user message.
+- `request_id`: free-form request identifier for tracing/logging.
+- `timeout_s`: optional timeout in seconds (best-effort depending on provider).
+- `max_retries` and `retry_backoff_s`: retry count and exponential backoff base delay.
+
+Async counterparts are available as `async_generate_response`, `async_generate_image`, and `async_list_models`.
+
 ## GeminiClient
 
 ### Usage
@@ -326,6 +352,15 @@ response_via_router = llm_client.generate_response(
     max_tokens=1500,
 )
 
+# async usage
+# response_via_router = await llm_client.async_generate_response(
+#     provider="openai",
+#     api_key="sk-your-api-key",
+#     messages=[{"role": "system", "content": "You are concise."}],
+#     prompt="Summarize the plan.",
+#     model="gpt-4o-mini",
+# )
+
 gemini_response = llm_client.generate_response(
     provider="gemini",                         # google-genai is installed with llmconnector
     api_key="your-gemini-api-key",
@@ -373,10 +408,15 @@ for model in llm_client.list_models(provider="openai", api_key="sk-your-api-key"
 | `provider` | `str` | Yes | Registered provider key (default registry includes `'openai'`, `'gemini'`, `'anthropic'`, `'grok'`/`'xai'`). |
 | `api_key` | `str` | Yes | Provider-specific API key. |
 | `prompt` | `Optional[str]` | Conditional | Plain-text prompt. Required unless `images` is supplied. |
+| `messages` | `Optional[Sequence[dict]]` | No | Chat-style messages (`role`, `content`). |
 | `model` | `str` | Yes | Provider-specific model identifier. |
 | `max_tokens` | `int` | No | Defaults to `32000`. |
 | `reasoning_effort` | `Optional[str]` | No | Reasoning hint forwarded when supported. |
 | `images` | `Optional[Sequence[str \| Path]]` | No | Image references forwarded to the provider implementation. |
+| `request_id` | `Optional[str]` | No | Request identifier for tracing/logging. |
+| `timeout_s` | `Optional[float]` | No | Timeout in seconds (best-effort). |
+| `max_retries` | `Optional[int]` | No | Retry count for transient failures. |
+| `retry_backoff_s` | `Optional[float]` | No | Base delay (seconds) for exponential backoff. |
 
 Use `LLMClient.register_provider(name, client)` to add additional providers that implement
 `generate_response` with the same signature.
@@ -399,6 +439,9 @@ Examples:
 # Generate a response
 client_cli respond --provider openai --model gpt-4o --prompt "Hello!"
 
+# Generate with retry/timeout controls
+client_cli respond --provider openai --model gpt-4o --prompt "Hello!" --timeout-s 30 --max-retries 2
+
 # List models for one provider (human-readable)
 client_cli models --provider gemini
 

ccs_llmconnector-1.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+ccs_llmconnector-1.1.1.dist-info/licenses/LICENSE,sha256=rPcz2YmBB9VUWZTLJcRO_B4jKDpqmGRYi2eSI-unysg,1083
+llmconnector/__init__.py,sha256=w68d7BCkhjjqMaOG9VDkPoYR4PNbv8NJqGmAV_Vyn6g,1358
+llmconnector/anthropic_client.py,sha256=hGFZlUQ4yAs_H8StxWzHAYmqwgNT6lGI4yW8UmKhtm8,13260
+llmconnector/client.py,sha256=2rhDpcBKKbQ1kGp7-Bk8ci_VVe9DEEvBf9nH4hKwg3w,13849
+llmconnector/client_cli.py,sha256=ojLPNJ14lFycsLWtEMtdGpV033v2-23qPMuWqFlnySA,11463
+llmconnector/gemini_client.py,sha256=_XPy6C5WQeuP_GY2eb3dy4DMFX9Oj8DRhb9u7XA5TfI,19155
+llmconnector/grok_client.py,sha256=uicZI28-vw7go677zZB5MTkw5aqWp2UP_GaguNUU99o,11254
+llmconnector/openai_client.py,sha256=wvrEFzltg8PctM2DcNZ_7qmRPpF-CB8WQek6iYoRvR4,11051
+llmconnector/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+llmconnector/types.py,sha256=JhXKjKncdUB2yPd-bqjOUnl-4Wgs6GIleDMChmwPW8w,1287
+llmconnector/utils.py,sha256=Tw6wQLh7Cjk6igLJ-MnYGSSPJBUGl5-7R1xB0Aj7o8Y,2047
+ccs_llmconnector-1.1.1.dist-info/METADATA,sha256=k4esAN7SCw583miw_IqV9sehyt0GGcgGylpLLPAL35s,17001
+ccs_llmconnector-1.1.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+ccs_llmconnector-1.1.1.dist-info/entry_points.txt,sha256=eFvLY3nHAG_QhaKlemhhK7echfezW0KiMdSNMZOStLc,60
+ccs_llmconnector-1.1.1.dist-info/top_level.txt,sha256=Doer7TAUsN8UXQfPHPNsuBXVNCz2uV-Q0v4t4fwv_MM,13
+ccs_llmconnector-1.1.1.dist-info/RECORD,,

{ccs_llmconnector-1.0.6.dist-info → ccs_llmconnector-1.1.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

llmconnector/__init__.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from .client import LLMClient
+from .types import ImageInput, Message, MessageSequence
 
 if TYPE_CHECKING:
     from .anthropic_client import AnthropicClient
@@ -12,7 +13,16 @@ if TYPE_CHECKING:
     from .grok_client import GrokClient
     from .openai_client import OpenAIResponsesClient
 
-__all__ = ["LLMClient", "OpenAIResponsesClient", "GeminiClient", "AnthropicClient", "GrokClient"]
+__all__ = [
+    "LLMClient",
+    "OpenAIResponsesClient",
+    "GeminiClient",
+    "AnthropicClient",
+    "GrokClient",
+    "ImageInput",
+    "Message",
+    "MessageSequence",
+]
 
 
 def __getattr__(name: str) -> Any:

llmconnector/anthropic_client.py

@@ -6,13 +6,14 @@ import base64
 import mimetypes
 from pathlib import Path
 import logging
-from typing import Optional, Sequence, Union
-from urllib.error import URLError
+from typing import Optional, Sequence
 from urllib.request import urlopen
 
 from anthropic import APIError, Anthropic
 
-ImageInput = Union[str, Path]
+from .types import ImageInput, MessageSequence, normalize_messages
+from .utils import clamp_retries, run_sync_in_thread, run_with_retries
+
 logger = logging.getLogger(__name__)
 
 
@@ -23,11 +24,16 @@ class AnthropicClient:
         self,
         *,
         api_key: str,
-        prompt: 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 Anthropic model.
 
@@ -38,6 +44,11 @@ class AnthropicClient:
             max_tokens: Cap for tokens across the entire exchange, defaults to 32000.
             reasoning_effort: Included for API parity; currently unused by the Anthropic SDK.
             images: Optional collection of image references (local paths, URLs, or data 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.
@@ -49,59 +60,124 @@ class AnthropicClient:
         """
         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 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.")
 
-        content_blocks: list[dict] = []
-        if prompt:
-            content_blocks.append({"type": "text", "text": prompt})
+        normalized_messages = normalize_messages(prompt=prompt, messages=messages)
+        message_payloads: list[dict] = []
+        for message in normalized_messages:
+            blocks: list[dict] = []
+            if message["content"]:
+                blocks.append({"type": "text", "text": message["content"]})
+            message_payloads.append({"role": message["role"], "content": blocks})
 
         if images:
-            for image in images:
-                content_blocks.append(self._to_image_block(image))
+            image_blocks = [self._to_image_block(image) for image in images]
+            target_index = next(
+                (
+                    index
+                    for index in range(len(message_payloads) - 1, -1, -1)
+                    if message_payloads[index]["role"] == "user"
+                ),
+                None,
+            )
+            if target_index is None:
+                message_payloads.append({"role": "user", "content": image_blocks})
+            else:
+                message_payloads[target_index]["content"].extend(image_blocks)
 
-        if not content_blocks:
+        if not message_payloads or not any(msg["content"] for msg in message_payloads):
             raise ValueError("No content provided for response generation.")
 
-        client = Anthropic(api_key=api_key)
-
-        try:
-            response = client.messages.create(
-                model=model,
-                max_tokens=max_tokens,
-                messages=[{"role": "user", "content": content_blocks}],
-            )
-        except Exception as exc:
-            logger.exception("Anthropic messages.create failed: %s", exc)
-            raise
-
-        text_blocks: list[str] = []
-        for block in getattr(response, "content", []) or []:
-            if getattr(block, "type", None) == "text":
-                text = getattr(block, "text", None)
-                if text:
-                    text_blocks.append(text)
-
-        if text_blocks:
-            result_text = "".join(text_blocks)
+        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 = Anthropic(**client_kwargs)
+
+            try:
+                response = client.messages.create(
+                    model=model,
+                    max_tokens=max_tokens,
+                    messages=message_payloads,
+                )
+            except Exception as exc:
+                logger.exception(
+                    "Anthropic messages.create failed: %s request_id=%s",
+                    exc,
+                    request_id,
+                )
+                raise
+
+            text_blocks: list[str] = []
+            for block in getattr(response, "content", []) or []:
+                if getattr(block, "type", None) == "text":
+                    text = getattr(block, "text", None)
+                    if text:
+                        text_blocks.append(text)
+
+            if text_blocks:
+                result_text = "".join(text_blocks)
+                logger.info(
+                    "Anthropic messages.create succeeded: model=%s images=%d text_len=%d request_id=%s",
+                    model,
+                    len(images or []),
+                    len(result_text or ""),
+                    request_id,
+                )
+                return result_text
+
+            # Treat successful calls without textual content as a successful, empty response
+            # rather than raising. This aligns with callers that handle empty outputs gracefully.
             logger.info(
-                "Anthropic messages.create succeeded: model=%s images=%d text_len=%d",
+                "Anthropic messages.create succeeded with no text: model=%s images=%d request_id=%s",
                 model,
                 len(images or []),
-                len(result_text or ""),
+                request_id,
+            )
+            return ""
+
+        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,
             )
-            return result_text
-
-        # Treat successful calls without textual content as a successful, empty response
-        # rather than raising. This aligns with callers that handle empty outputs gracefully.
-        logger.info(
-            "Anthropic messages.create succeeded with no text: model=%s images=%d",
-            model,
-            len(images or []),
         )
-        return ""
 
     def generate_image(
         self,
@@ -119,35 +195,102 @@ class AnthropicClient:
         """
         raise NotImplementedError("Image generation is not implemented for Anthropic.")
 
-    def list_models(self, *, api_key: str) -> list[dict[str, Optional[str]]]:
+    async def async_generate_image(
+        self,
+        *,
+        api_key: str,
+        prompt: str,
+        model: str,
+        image_size: str = "2K",
+        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,
+                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 Anthropic account."""
         if not api_key:
             raise ValueError("api_key must be provided.")
 
-        client = Anthropic(api_key=api_key)
-        models: list[dict[str, Optional[str]]] = []
-
-        try:
-            iterator = client.models.list()
-        except Exception as exc:
-            logger.exception("Anthropic list models failed: %s", exc)
-            raise
-
-        for model in iterator:
-            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
+        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 = Anthropic(**client_kwargs)
+            models: list[dict[str, Optional[str]]] = []
+
+            try:
+                iterator = client.models.list()
+            except Exception as exc:
+                logger.exception(
+                    "Anthropic list models failed: %s request_id=%s",
+                    exc,
+                    request_id,
+                )
+                raise
+
+            for model in iterator:
+                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})
 
-            display_name = getattr(model, "display_name", None)
-            if display_name is None and isinstance(model, dict):
-                display_name = model.get("display_name")
+            logger.info(
+                "Anthropic list_models succeeded: count=%d request_id=%s",
+                len(models),
+                request_id,
+            )
+            return models
 
-            models.append({"id": model_id, "display_name": display_name})
+        return run_with_retries(
+            func=_run_request,
+            max_retries=retry_count,
+            retry_backoff_s=retry_backoff_s,
+            request_id=request_id,
+        )
 
-        logger.info("Anthropic list_models succeeded: count=%d", len(models))
-        return models
+    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,
+            )
+        )
 
     @staticmethod
     def _to_image_block(image: ImageInput) -> dict: