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

{ccs_llmconnector-1.0.3.dist-info → ccs_llmconnector-1.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccs-llmconnector
-Version: 1.0.3
+Version: 1.0.5
 Summary: Lightweight wrapper around different LLM provider Python SDK Responses APIs.
 Author: CCS
 License: MIT
@@ -91,10 +91,36 @@ vision_response = client.generate_response(
 | `reasoning_effort` | `Optional[str]` | No | Present for parity with the OpenAI client; currently ignored by the Gemini SDK. |
 | `images` | `Optional[Sequence[str \| Path]]` | No | Image references (local paths, URLs, or data URLs) read and forwarded to the Gemini SDK. |
 
-The method returns the generated model output as a plain string. Optional image
 references are automatically converted into the appropriate `types.Part` instances,
 allowing you to mix text and visuals in a single request.
 
+### Image Generation
+
+Use `generate_image` to create images using Gemini's image generation models (e.g., `gemini-3-pro-image-preview`).
+
+```python
+image_bytes = client.generate_image(
+    api_key="your-gemini-api-key",
+    prompt="Generate an infographic of the current weather in Tokyo.",
+    model="gemini-3-pro-image-preview",
+    image_size="2K",  # Optional, defaults to "2K"
+)
+
+with open("weather_tokyo.png", "wb") as f:
+    f.write(image_bytes)
+```
+
+You can also provide an input image for editing tasks:
+
+```python
+image_bytes = client.generate_image(
+    api_key="your-gemini-api-key",
+    prompt="Make the background a sunset.",
+    model="gemini-3-pro-image-preview",
+    image="/path/to/original.png",
+)
+```
+
 ### Listing models
 
 Use `list_models` to enumerate the Gemini models available to your account:
@@ -318,6 +344,14 @@ anthropic_response = llm_client.generate_response(
 # Additional providers can be registered at runtime:
 # llm_client.register_provider("custom", CustomProviderClient())
 # llm_client.generate_response(provider="custom", ...)
+
+# Image generation (currently only supported by Gemini)
+image_bytes = llm_client.generate_image(
+    provider="gemini",
+    api_key="your-gemini-api-key",
+    prompt="A futuristic city",
+    model="gemini-3-pro-image-preview",
+)
 ```
 
 ### Listing models

ccs_llmconnector-1.0.5.dist-info/RECORD

@@ -0,0 +1,14 @@
+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,,

{ccs_llmconnector-1.0.3.dist-info → ccs_llmconnector-1.0.5.dist-info}/licenses/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2025 CCS
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
+MIT License
+
+Copyright (c) 2025 CCS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

llmconnector/__init__.py

@@ -1,39 +1,39 @@
-"""Public package interface for llmconnector."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from .client import LLMClient
-
-if TYPE_CHECKING:
-    from .anthropic_client import AnthropicClient
-    from .gemini_client import GeminiClient
-    from .grok_client import GrokClient
-    from .openai_client import OpenAIResponsesClient
-
-__all__ = ["LLMClient", "OpenAIResponsesClient", "GeminiClient", "AnthropicClient", "GrokClient"]
-
-
-def __getattr__(name: str) -> Any:
-    if name == "OpenAIResponsesClient":
-        from .openai_client import OpenAIResponsesClient as _OpenAIResponsesClient
-
-        return _OpenAIResponsesClient
-    if name == "GeminiClient":
-        from .gemini_client import GeminiClient as _GeminiClient
-
-        return _GeminiClient
-    if name == "AnthropicClient":
-        from .anthropic_client import AnthropicClient as _AnthropicClient
-
-        return _AnthropicClient
-    if name == "GrokClient":
-        from .grok_client import GrokClient as _GrokClient
-
-        return _GrokClient
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-
-def __dir__() -> list[str]:
-    return sorted(__all__)
+"""Public package interface for llmconnector."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .client import LLMClient
+
+if TYPE_CHECKING:
+    from .anthropic_client import AnthropicClient
+    from .gemini_client import GeminiClient
+    from .grok_client import GrokClient
+    from .openai_client import OpenAIResponsesClient
+
+__all__ = ["LLMClient", "OpenAIResponsesClient", "GeminiClient", "AnthropicClient", "GrokClient"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "OpenAIResponsesClient":
+        from .openai_client import OpenAIResponsesClient as _OpenAIResponsesClient
+
+        return _OpenAIResponsesClient
+    if name == "GeminiClient":
+        from .gemini_client import GeminiClient as _GeminiClient
+
+        return _GeminiClient
+    if name == "AnthropicClient":
+        from .anthropic_client import AnthropicClient as _AnthropicClient
+
+        return _AnthropicClient
+    if name == "GrokClient":
+        from .grok_client import GrokClient as _GrokClient
+
+        return _GrokClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

llmconnector/anthropic_client.py

@@ -1,217 +1,233 @@
-"""Thin wrapper around the Anthropic Messages API via the `anthropic` SDK."""
-
-from __future__ import annotations
-
-import base64
-import mimetypes
-from pathlib import Path
-import logging
-from typing import Optional, Sequence, Union
-from urllib.error import URLError
-from urllib.request import urlopen
-
-from anthropic import APIError, Anthropic
-
-ImageInput = Union[str, Path]
-logger = logging.getLogger(__name__)
-
-
-class AnthropicClient:
-    """Convenience wrapper around the Anthropic Messages 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 Anthropic model.
-
-        Args:
-            api_key: API key used to authenticate with Anthropic.
-            prompt: Natural-language instruction or query for the model.
-            model: Identifier of the Anthropic model to target (for example, ``"claude-3-5-sonnet-20241022"``).
-            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).
-
-        Returns:
-            The text output produced by the model.
-
-        Raises:
-            ValueError: If required arguments are missing or the request payload is empty.
-            URLError: If an image URL cannot be retrieved.
-            APIError: If the underlying Anthropic 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.")
-
-        content_blocks: list[dict] = []
-        if prompt:
-            content_blocks.append({"type": "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.")
-
-        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)
-            logger.info(
-                "Anthropic messages.create succeeded: model=%s images=%d text_len=%d",
-                model,
-                len(images or []),
-                len(result_text or ""),
-            )
-            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 list_models(self, *, api_key: str) -> 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
-
-            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("Anthropic list_models succeeded: count=%d", len(models))
-        return models
-
-    @staticmethod
-    def _to_image_block(image: ImageInput) -> dict:
-        """Convert an image reference into an Anthropic content block."""
-        if isinstance(image, Path):
-            return _block_from_path(image)
-
-        if image.startswith("data:"):
-            return _block_from_data_url(image)
-
-        if image.startswith(("http://", "https://")):
-            return _block_from_url(image)
-
-        return _block_from_path(Path(image))
-
-
-def _block_from_path(path: Path) -> dict:
-    """Create an image block from a local filesystem path."""
-    expanded = path.expanduser()
-    data = expanded.read_bytes()
-    encoded = base64.b64encode(data).decode("utf-8")
-    mime_type = mimetypes.guess_type(expanded.name)[0] or "application/octet-stream"
-
-    return {
-        "type": "image",
-        "source": {
-            "type": "base64",
-            "media_type": mime_type,
-            "data": encoded,
-        },
-    }
-
-
-def _block_from_url(url: str) -> dict:
-    """Create an image block by downloading content from a URL."""
-    with urlopen(url) as response:
-        data = response.read()
-        mime_type = response.info().get_content_type()
-
-    if not mime_type or mime_type == "application/octet-stream":
-        mime_type = mimetypes.guess_type(url)[0] or "application/octet-stream"
-
-    encoded = base64.b64encode(data).decode("utf-8")
-
-    return {
-        "type": "image",
-        "source": {
-            "type": "base64",
-            "media_type": mime_type,
-            "data": encoded,
-        },
-    }
-
-
-def _block_from_data_url(data_url: str) -> dict:
-    """Create an image block from a data URL."""
-    header, encoded = data_url.split(",", 1)
-    metadata = header[len("data:") :]
-    mime_type = "application/octet-stream"
-    is_base64 = False
-
-    if ";" in metadata:
-        mime_type_part, _, remainder = metadata.partition(";")
-        if mime_type_part:
-            mime_type = mime_type_part
-        is_base64 = "base64" in remainder
-    elif metadata:
-        mime_type = metadata
-
-    if is_base64:
-        data_b64 = encoded
-    else:
-        data_bytes = encoded.encode("utf-8")
-        data_b64 = base64.b64encode(data_bytes).decode("utf-8")
-
-    return {
-        "type": "image",
-        "source": {
-            "type": "base64",
-            "media_type": mime_type or "application/octet-stream",
-            "data": data_b64,
-        },
-    }
+"""Thin wrapper around the Anthropic Messages API via the `anthropic` SDK."""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from pathlib import Path
+import logging
+from typing import Optional, Sequence, Union
+from urllib.error import URLError
+from urllib.request import urlopen
+
+from anthropic import APIError, Anthropic
+
+ImageInput = Union[str, Path]
+logger = logging.getLogger(__name__)
+
+
+class AnthropicClient:
+    """Convenience wrapper around the Anthropic Messages 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 Anthropic model.
+
+        Args:
+            api_key: API key used to authenticate with Anthropic.
+            prompt: Natural-language instruction or query for the model.
+            model: Identifier of the Anthropic model to target (for example, ``"claude-3-5-sonnet-20241022"``).
+            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).
+
+        Returns:
+            The text output produced by the model.
+
+        Raises:
+            ValueError: If required arguments are missing or the request payload is empty.
+            URLError: If an image URL cannot be retrieved.
+            APIError: If the underlying Anthropic 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.")
+
+        content_blocks: list[dict] = []
+        if prompt:
+            content_blocks.append({"type": "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.")
+
+        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)
+            logger.info(
+                "Anthropic messages.create succeeded: model=%s images=%d text_len=%d",
+                model,
+                len(images or []),
+                len(result_text or ""),
+            )
+            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,
+        *,
+        api_key: str,
+        prompt: str,
+        model: str,
+        image_size: str = "2K",
+        image: Optional[ImageInput] = None,
+    ) -> bytes:
+        """Generate an image using the Anthropic API.
+
+        Raises:
+            NotImplementedError: This method is not yet implemented for Anthropic.
+        """
+        raise NotImplementedError("Image generation is not implemented for Anthropic.")
+
+    def list_models(self, *, api_key: str) -> 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
+
+            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("Anthropic list_models succeeded: count=%d", len(models))
+        return models
+
+    @staticmethod
+    def _to_image_block(image: ImageInput) -> dict:
+        """Convert an image reference into an Anthropic content block."""
+        if isinstance(image, Path):
+            return _block_from_path(image)
+
+        if image.startswith("data:"):
+            return _block_from_data_url(image)
+
+        if image.startswith(("http://", "https://")):
+            return _block_from_url(image)
+
+        return _block_from_path(Path(image))
+
+
+def _block_from_path(path: Path) -> dict:
+    """Create an image block from a local filesystem path."""
+    expanded = path.expanduser()
+    data = expanded.read_bytes()
+    encoded = base64.b64encode(data).decode("utf-8")
+    mime_type = mimetypes.guess_type(expanded.name)[0] or "application/octet-stream"
+
+    return {
+        "type": "image",
+        "source": {
+            "type": "base64",
+            "media_type": mime_type,
+            "data": encoded,
+        },
+    }
+
+
+def _block_from_url(url: str) -> dict:
+    """Create an image block by downloading content from a URL."""
+    with urlopen(url) as response:
+        data = response.read()
+        mime_type = response.info().get_content_type()
+
+    if not mime_type or mime_type == "application/octet-stream":
+        mime_type = mimetypes.guess_type(url)[0] or "application/octet-stream"
+
+    encoded = base64.b64encode(data).decode("utf-8")
+
+    return {
+        "type": "image",
+        "source": {
+            "type": "base64",
+            "media_type": mime_type,
+            "data": encoded,
+        },
+    }
+
+
+def _block_from_data_url(data_url: str) -> dict:
+    """Create an image block from a data URL."""
+    header, encoded = data_url.split(",", 1)
+    metadata = header[len("data:") :]
+    mime_type = "application/octet-stream"
+    is_base64 = False
+
+    if ";" in metadata:
+        mime_type_part, _, remainder = metadata.partition(";")
+        if mime_type_part:
+            mime_type = mime_type_part
+        is_base64 = "base64" in remainder
+    elif metadata:
+        mime_type = metadata
+
+    if is_base64:
+        data_b64 = encoded
+    else:
+        data_bytes = encoded.encode("utf-8")
+        data_b64 = base64.b64encode(data_bytes).decode("utf-8")
+
+    return {
+        "type": "image",
+        "source": {
+            "type": "base64",
+            "media_type": mime_type or "application/octet-stream",
+            "data": data_b64,
+        },
+    }