ccs-llmconnector 1.0.0__py3-none-any.whl

llmconnector/client.py

@@ -0,0 +1,148 @@
+"""Provider-agnostic entry point for working with large language models."""
+
+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 list_models(self, *, api_key: str) -> Sequence[dict[str, Optional[str]]]:
+        ...
+
+
+class LLMClient:
+    """Central client capable of routing requests to different providers."""
+
+    def __init__(
+        self,
+        providers: Optional[Dict[str, SupportsGenerateResponse]] = None,
+    ) -> None:
+        self._providers: Dict[str, SupportsGenerateResponse] = {}
+        default_providers = providers or self._discover_default_providers()
+        for name, client in default_providers.items():
+            self.register_provider(name, client)
+
+        if not self._providers:
+            raise RuntimeError(
+                "No provider implementations registered. Install the required extras "
+                "for your target provider (e.g. `pip install openai`)."
+            )
+
+    def register_provider(self, name: str, client: SupportsGenerateResponse) -> None:
+        """Register or overwrite a provider implementation."""
+        if not name:
+            raise ValueError("Provider name must be provided.")
+        if client is None:
+            raise ValueError("Provider client must be provided.")
+
+        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:
+        """Generate a response using the selected provider."""
+        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}."
+            )
+
+        return provider_client.generate_response(
+            api_key=api_key,
+            prompt=prompt,
+            model=model,
+            max_tokens=max_tokens,
+            reasoning_effort=reasoning_effort,
+            images=images,
+        )
+
+    def list_models(
+        self,
+        *,
+        provider: str,
+        api_key: str,
+    ) -> Sequence[dict[str, Optional[str]]]:
+        """List models available for the specified provider."""
+        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}."
+            )
+
+        return provider_client.list_models(api_key=api_key)
+
+    @staticmethod
+    def _discover_default_providers() -> Dict[str, SupportsGenerateResponse]:
+        providers: Dict[str, SupportsGenerateResponse] = {}
+        try:
+            from .openai_client import OpenAIResponsesClient  # type: ignore
+        except ModuleNotFoundError as exc:
+            if exc.name != "openai":
+                raise
+            return providers
+
+        providers["openai"] = OpenAIResponsesClient()
+
+        try:
+            from .gemini_client import GeminiClient  # type: ignore
+        except ModuleNotFoundError as exc:
+            if exc.name not in {"google", "google.genai"}:
+                raise
+        else:
+            providers["gemini"] = GeminiClient()
+
+        try:
+            from .anthropic_client import AnthropicClient  # type: ignore
+        except ModuleNotFoundError as exc:
+            if exc.name != "anthropic":
+                raise
+        else:
+            providers["anthropic"] = AnthropicClient()
+
+        try:
+            from .grok_client import GrokClient  # type: ignore
+        except ModuleNotFoundError as exc:
+            if exc.name != "xai_sdk":
+                raise
+        else:
+            grok_client = GrokClient()
+            providers["grok"] = grok_client
+            providers.setdefault("xai", grok_client)
+
+        return providers

llmconnector/client_cli.py

@@ -0,0 +1,325 @@
+"""Command-line client for llmconnector.
+
+Reads the API key from an environment variable derived from the provider name
+("{PROVIDER}_API_KEY", e.g. OPENAI_API_KEY) and exposes
+simple commands to generate a response or list available models for a
+provider.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Sequence
+
+# Support both package execution and direct file execution.
+# When run as a script (no package), add the parent of this file's directory to sys.path
+# so that `import llmconnector` resolves.
+try:
+    if __package__ in (None, ""):
+        # Running as a script: add repo/src to path
+        _here = os.path.dirname(os.path.abspath(__file__))
+        _pkg_root = os.path.dirname(_here)
+        if _pkg_root not in sys.path:
+            sys.path.insert(0, _pkg_root)
+        from llmconnector.client import LLMClient  # type: ignore
+    else:
+        from .client import LLMClient
+except Exception:  # pragma: no cover - defensive import fallback
+    # Last-resort fallback if the above logic fails in unusual environments
+    from llmconnector.client import LLMClient  # type: ignore
+
+
+def _env_api_key(provider: str) -> str:
+    env_name = f"{provider.upper()}_API_KEY"
+    api_key = os.environ.get(env_name, "")
+    if not api_key:
+        raise SystemExit(
+            f"Missing {env_name} environment variable. Set it before running."
+        )
+    return api_key
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="client_cli",
+        description="CLI for provider-agnostic LLM requests",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # respond: generate a model response
+    p_respond = subparsers.add_parser(
+        "respond", help="Generate a response from a provider model"
+    )
+    p_respond.add_argument(
+        "--provider",
+        required=False,
+        help="Provider to use (e.g. openai, gemini, anthropic, grok). If omitted, you will be prompted.",
+    )
+    p_respond.add_argument(
+        "--model",
+        required=False,
+        help="Model identifier for the provider (e.g. gpt-4o). If omitted, you will be prompted.",
+    )
+    p_respond.add_argument(
+        "--prompt",
+        default="",
+        help="Text prompt to send (omit if only using images)",
+    )
+    p_respond.add_argument(
+        "--image",
+        action="append",
+        dest="images",
+        default=None,
+        help="Image path or URL; may be provided multiple times",
+    )
+    p_respond.add_argument(
+        "--max-tokens",
+        type=int,
+        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",
+    )
+
+    # models: list available models
+    p_models = subparsers.add_parser(
+        "models", help="List models available to the provider"
+    )
+    p_models.add_argument(
+        "--provider",
+        required=False,
+        help="Provider to query (e.g. openai, gemini, anthropic, grok). If omitted, you will be prompted.",
+    )
+    p_models.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON (default is human-readable)",
+    )
+
+    # all-models: list models for all registered providers
+    p_all_models = subparsers.add_parser(
+        "all-models", help="List models for all registered providers"
+    )
+    p_all_models.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON (default is human-readable)",
+    )
+
+    return parser
+
+
+def _cmd_respond(args: argparse.Namespace) -> int:
+    client = LLMClient()
+    provider = args.provider
+    if not provider:
+        # Try to hint known providers
+        try:
+            known = sorted(LLMClient._discover_default_providers().keys())  # type: ignore[attr-defined]
+        except Exception:
+            known = []
+        hint = f" ({'/'.join(known)})" if known else ""
+        provider = input(f"Provider{hint}: ").strip()
+        if not provider:
+            print("Error: provider is required.", file=sys.stderr)
+            return 2
+
+    api_key = _env_api_key(provider)
+
+    model = args.model
+    if not model:
+        model = input("Model id: ").strip()
+        if not model:
+            print("Error: model is required.", file=sys.stderr)
+            return 2
+
+    prompt = args.prompt
+    images: Sequence[str] | None = args.images
+    if not prompt and not images:
+        prompt = input("Prompt: ")
+        if not prompt and not images:
+            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,
+        )
+    except Exception as exc:  # pragma: no cover - CLI surface
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    print(output)
+    return 0
+
+
+def _cmd_models(args: argparse.Namespace) -> int:
+    client = LLMClient()
+    provider = args.provider
+    if not provider:
+        try:
+            known = sorted(LLMClient._discover_default_providers().keys())  # type: ignore[attr-defined]
+        except Exception:
+            known = []
+        hint = f" ({'/'.join(known)})" if known else ""
+        provider = input(f"Provider{hint}: ").strip()
+        if not provider:
+            print("Error: provider is required.", file=sys.stderr)
+            return 2
+
+    api_key = _env_api_key(provider)
+    try:
+        models = client.list_models(provider=provider, api_key=api_key)
+    except Exception as exc:  # pragma: no cover - CLI surface
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(models, indent=2))
+    else:
+        if not models:
+            print("No models found.")
+        else:
+            for m in models:
+                mid = m.get("id") or "<unknown>"
+                name = m.get("display_name") or ""
+                if name:
+                    print(f"{mid} - {name}")
+                else:
+                    print(mid)
+    return 0
+
+
+def _env_api_key_with_fallbacks(provider: str) -> tuple[str | None, list[str]]:
+    """Return the API key for a provider, trying common env var fallbacks.
+
+    Returns a tuple of (api_key_or_none, tried_env_names).
+    """
+    name = provider.upper()
+    # Default convention first
+    env_names: list[str] = [f"{name}_API_KEY"]
+
+    # Provider-specific fallbacks commonly used by SDKs/docs
+    if provider.lower() == "gemini":
+        env_names.extend(["GOOGLE_API_KEY"])  # google-genai default
+    elif provider.lower() in {"grok", "xai"}:
+        env_names.extend(["XAI_API_KEY", "GROK_API_KEY"])  # prefer XAI
+    elif provider.lower() == "openai":
+        # OPENAI_API_KEY already covered by default
+        pass
+    elif provider.lower() == "anthropic":
+        # ANTHROPIC_API_KEY already covered by default
+        pass
+
+    for env_name in env_names:
+        val = os.environ.get(env_name)
+        if val:
+            return val, env_names
+
+    return None, env_names
+
+
+def _cmd_all_models(args: argparse.Namespace) -> int:
+    client = LLMClient()
+
+    # Group provider names by underlying client instance to avoid duplicates
+    by_client: dict[int, dict[str, object]] = {}
+    for name, prov_client in getattr(client, "_providers", {}).items():  # type: ignore[attr-defined]
+        key = id(prov_client)
+        group = by_client.setdefault(key, {"names": [], "client": prov_client})
+        names = group["names"]  # type: ignore[assignment]
+        assert isinstance(names, list)
+        names.append(name)
+
+    results: list[dict[str, object]] = []
+    for entry in by_client.values():
+        names = sorted(entry["names"])  # type: ignore[index]
+        primary = names[0]
+        display_name = "/".join(names)
+
+        api_key, tried = _env_api_key_with_fallbacks(primary)
+        if not api_key:
+            results.append(
+                {
+                    "provider": display_name,
+                    "error": f"missing API key (tried: {', '.join(tried)})",
+                    "models": [],
+                }
+            )
+            continue
+
+        try:
+            models = client.list_models(provider=primary, api_key=api_key)
+        except Exception as exc:  # pragma: no cover - CLI surface
+            results.append(
+                {
+                    "provider": display_name,
+                    "error": str(exc),
+                    "models": [],
+                }
+            )
+            continue
+
+        results.append({"provider": display_name, "models": models})
+
+    if args.json:
+        print(json.dumps(results, indent=2))
+    else:
+        if not results:
+            print("No providers registered.")
+            return 0
+
+        for item in results:
+            provider_label = str(item.get("provider", "<unknown>"))
+            print(f"== {provider_label} ==")
+            if item.get("error"):
+                print(f"  Skipped: {item['error']}")
+                continue
+            models = item.get("models") or []
+            if not models:
+                print("  No models found.")
+                continue
+            for m in models:  # type: ignore[assignment]
+                if not isinstance(m, dict):
+                    print(f"  {m}")
+                    continue
+                mid = m.get("id") or "<unknown>"
+                name = m.get("display_name") or ""
+                if name:
+                    print(f"  {mid} - {name}")
+                else:
+                    print(f"  {mid}")
+
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "respond":
+        return _cmd_respond(args)
+    if args.command == "models":
+        return _cmd_models(args)
+    if args.command == "all-models":
+        return _cmd_all_models(args)
+
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

llmconnector/gemini_client.py

@@ -0,0 +1,191 @@
+"""Thin wrapper around the Google Gemini API via the google-genai SDK."""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Optional, Sequence, Union
+from urllib.error import URLError
+from urllib.request import urlopen
+
+from google import genai
+from google.genai import types
+
+ImageInput = Union[str, Path]
+
+
+class GeminiClient:
+    """Convenience wrapper around the Google Gemini SDK."""
+
+    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 Gemini model.
+
+        Args:
+            api_key: API key used to authenticate with the Gemini API.
+            prompt: Natural-language instruction or query for the model.
+            model: Identifier of the Gemini model to target (for example, ``"gemini-2.5-flash"``).
+            max_tokens: Cap for tokens across the entire exchange, defaults to 32000.
+            reasoning_effort: Included for API parity; currently unused by the Gemini 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.
+            google.genai.errors.APIError: If the underlying Gemini 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.")
+
+        parts: list[types.Part] = []
+        if prompt:
+            parts.append(types.Part.from_text(text=prompt))
+
+        if images:
+            for image in images:
+                parts.append(self._to_image_part(image))
+
+        if not parts:
+            raise ValueError("No content provided for response generation.")
+
+        content = types.Content(role="user", parts=parts)
+
+        config = types.GenerateContentConfig(max_output_tokens=max_tokens)
+        # reasoning_effort is accepted for compatibility but not currently applied because the
+        # Gemini SDK does not expose an equivalent configuration parameter.
+
+        client = genai.Client(api_key=api_key)
+        try:
+            response = client.models.generate_content(
+                model=model,
+                contents=[content],
+                config=config,
+            )
+        finally:
+            closer = getattr(client, "close", None)
+            if callable(closer):
+                try:
+                    closer()
+                except Exception:
+                    pass
+
+        if response.text:
+            return response.text
+
+        candidate_texts: list[str] = []
+        for candidate in getattr(response, "candidates", []) or []:
+            content_obj = getattr(candidate, "content", None)
+            if not content_obj:
+                continue
+            for part in getattr(content_obj, "parts", []) or []:
+                text = getattr(part, "text", None)
+                if text:
+                    candidate_texts.append(text)
+
+        if candidate_texts:
+            return "\n".join(candidate_texts)
+
+        raise RuntimeError("Gemini response did not include any text output.")
+
+    def list_models(self, *, api_key: str) -> list[dict[str, Optional[str]]]:
+        """Return the models available to the authenticated Gemini account."""
+        if not api_key:
+            raise ValueError("api_key must be provided.")
+
+        models: list[dict[str, Optional[str]]] = []
+        client = genai.Client(api_key=api_key)
+        try:
+            for model in client.models.list():
+                model_id = getattr(model, "name", None)
+                if model_id is None and isinstance(model, dict):
+                    model_id = model.get("name")
+                if not model_id:
+                    continue
+
+                # Normalize IDs like "models/<id>" -> "<id>"
+                if isinstance(model_id, str) and model_id.startswith("models/"):
+                    model_id = model_id.split("/", 1)[1]
+
+                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})
+        finally:
+            closer = getattr(client, "close", None)
+            if callable(closer):
+                try:
+                    closer()
+                except Exception:
+                    pass
+
+        return models
+
+    @staticmethod
+    def _to_image_part(image: ImageInput) -> types.Part:
+        """Convert an image reference into a Gemini SDK part."""
+        if isinstance(image, Path):
+            return _part_from_path(image)
+
+        if image.startswith("data:"):
+            return _part_from_data_url(image)
+
+        if image.startswith(("http://", "https://")):
+            return _part_from_url(image)
+
+        return _part_from_path(Path(image))
+
+
+def _part_from_path(path: Path) -> types.Part:
+    """Create an image part from a local filesystem path."""
+    expanded = path.expanduser()
+    data = expanded.read_bytes()
+    mime_type = mimetypes.guess_type(expanded.name)[0] or "application/octet-stream"
+    return types.Part.from_bytes(data=data, mime_type=mime_type)
+
+
+def _part_from_url(url: str) -> types.Part:
+    """Create an image part 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"
+
+    return types.Part.from_bytes(data=data, mime_type=mime_type)
+
+
+def _part_from_data_url(data_url: str) -> types.Part:
+    """Create an image part from a data URL."""
+    header, encoded = data_url.split(",", 1)
+    metadata = header[len("data:") :]
+    mime_type = "application/octet-stream"
+
+    if ";" in metadata:
+        mime_type, _, metadata = metadata.partition(";")
+    elif metadata:
+        mime_type = metadata
+
+    if "base64" in metadata:
+        data = base64.b64decode(encoded)
+    else:
+        data = encoded.encode("utf-8")
+
+    return types.Part.from_bytes(data=data, mime_type=mime_type or "application/octet-stream")