ccs-llmconnector 1.0.0__tar.gz

ccs_llmconnector-1.0.0/LICENSE

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

ccs_llmconnector-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

ccs_llmconnector-1.0.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: ccs_llmconnector
+Version: 1.0.0
+Summary: Lightweight wrapper around different LLM provider Python SDK Responses APIs.
+Author: CCS
+License: MIT
+Project-URL: Homepage, https://cleancodesolutions.de
+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
+Dynamic: license-file
+
+# llmconnector
+
+`llmconnector` is a thin Python wrapper around leading large-language-model SDKs,
+including the OpenAI Responses API, Google's Gemini SDK, and Anthropic's Claude
+Messages API. It exposes a minimal interface that forwards the most common
+options such as API key, prompt, optional reasoning effort hints, token limits,
+and image inputs, and it includes helpers to enumerate the models available to
+your account with each provider.
+
+## Installation
+
+```bash
+pip install .
+```
+
+### Requirements
+
+- `openai` (installed automatically with the package)
+- `google-genai` (installed automatically with the package)
+- `anthropic` (installed automatically with the package)
+
+## Components
+
+- `OpenAIResponsesClient` - direct wrapper around the OpenAI Responses API, ideal when your project only targets OpenAI models. Includes a model discovery helper.
+- `GeminiClient` - thin wrapper around the Google Gemini SDK, usable when `google-genai` is installed. Includes a model discovery helper.
+- `AnthropicClient` - lightweight wrapper around the Anthropic Claude Messages API, usable when `anthropic` is installed. Includes a model discovery helper.
+- `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.
+
+## GeminiClient
+
+### Usage
+
+Use the `GeminiClient` when you want direct access to the Google Gemini SDK without
+going through the provider router.
+
+> Requires the `google-genai` Python package (installed automatically with `llmconnector`).
+
+```python
+from llmconnector import GeminiClient
+
+client = GeminiClient()
+
+text_response = client.generate_response(
+    api_key="your-gemini-api-key",
+    prompt="Summarize the key benefits of unit testing.",
+    model="gemini-2.5-flash",
+    max_tokens=2000,
+)
+
+vision_response = client.generate_response(
+    api_key="your-gemini-api-key",
+    prompt="Describe the main action in this image.",
+    model="gemini-2.5-flash",
+    images=[
+        "/absolute/path/to/local-image.png",
+        "https://example.com/sample.jpg",
+    ],
+)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | `str` | Yes | GEMINI or GOOGLE API key used for authentication. |
+| `prompt` | `Optional[str]` | Conditional | Plain-text prompt. Required unless `images` is supplied. |
+| `model` | `str` | Yes | Target model identifier, e.g. `gemini-2.5-flash`. |
+| `max_tokens` | `int` | No | Defaults to `32000`. Passed to the SDK as `max_output_tokens`. |
+| `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.
+
+### Listing models
+
+Use `list_models` to enumerate the Gemini models available to your account:
+
+```python
+from llmconnector import GeminiClient
+
+client = GeminiClient()
+for model in client.list_models(api_key="your-gemini-api-key"):
+    print(model["id"], model["display_name"])
+```
+
+## AnthropicClient
+
+### Usage
+
+Use the `AnthropicClient` when you want direct access to Anthropic's Claude Messages API.
+
+> Requires the `anthropic` Python package (installed automatically with `llmconnector`).
+
+```python
+from llmconnector import AnthropicClient
+
+client = AnthropicClient()
+
+text_response = client.generate_response(
+    api_key="sk-ant-api-key",
+    prompt="Summarize the key benefits of unit testing.",
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=2000,
+)
+
+vision_response = client.generate_response(
+    api_key="sk-ant-api-key",
+    prompt="Describe the main action in this image.",
+    model="claude-3-5-sonnet-20241022",
+    images=[
+        "/absolute/path/to/local-image.png",
+        "https://example.com/sample.jpg",
+    ],
+)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | `str` | Yes | Anthropic API key used for authentication. |
+| `prompt` | `Optional[str]` | Conditional | Plain-text prompt. Required unless `images` is supplied. |
+| `model` | `str` | Yes | Target model identifier, e.g. `claude-3-5-sonnet-20241022`. |
+| `max_tokens` | `int` | No | Defaults to `32000`. Passed to the SDK as `max_tokens`. |
+| `reasoning_effort` | `Optional[str]` | No | Present for parity with other clients; currently ignored by the Anthropic SDK. |
+| `images` | `Optional[Sequence[str \| Path]]` | No | Image references (local paths, URLs, or data URLs) read and converted to base64 blocks. |
+
+The method returns the generated model output as a plain string. Optional image
+references are automatically transformed into Anthropic `image` blocks so you can
+mix text and visual inputs in a single request.
+
+### Listing models
+
+Use `list_models` to enumerate the Anthropic models available to your account:
+
+```python
+from llmconnector import AnthropicClient
+
+client = AnthropicClient()
+for model in client.list_models(api_key="sk-ant-api-key"):
+    print(model["id"], model["display_name"])
+```
+
+## GrokClient
+
+### Usage
+
+Use the `GrokClient` when you want direct access to xAI's Grok chat API.
+
+> Requires the `xai-sdk` Python package (install manually with `pip install xai-sdk`). The SDK targets Python 3.10 and newer.
+
+```python
+from llmconnector import GrokClient
+
+client = GrokClient()
+
+text_response = client.generate_response(
+    api_key="xai-api-key",
+    prompt="Summarize the key benefits of unit testing.",
+    model="grok-3",
+    max_tokens=2000,
+)
+
+vision_response = client.generate_response(
+    api_key="xai-api-key",
+    prompt="Describe the main action in this image.",
+    model="grok-2-vision",
+    images=[
+        "/absolute/path/to/local-image.png",
+        "https://example.com/sample.jpg",
+    ],
+)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | `str` | Yes | xAI API key used for authentication. |
+| `prompt` | `Optional[str]` | Conditional | Plain-text prompt. Required unless `images` is supplied. |
+| `model` | `str` | Yes | Target model identifier, e.g. `grok-3`. |
+| `max_tokens` | `int` | No | Defaults to `32000`. Passed to the Grok API as `max_tokens`. |
+| `reasoning_effort` | `Optional[str]` | No | Hint for reasoning-focused models (`"low"` or `"high"`). |
+| `images` | `Optional[Sequence[str \| Path]]` | No | Image references (local paths converted to data URLs, or remote URLs passed through). |
+
+### Listing models
+
+Use `list_models` to enumerate the Grok language models available to your account:
+
+```python
+from llmconnector import GrokClient
+
+client = GrokClient()
+for model in client.list_models(api_key="xai-api-key"):
+    print(model["id"], model["display_name"])
+```
+
+## OpenAIResponsesClient
+
+### Usage
+
+Use the `OpenAIResponsesClient` when you want direct access to the OpenAI Responses API.
+
+> Requires the `openai` Python package. It is declared as a dependency of `llmconnector`, but you can also install it manually with `pip install openai`.
+
+```python
+from llmconnector import OpenAIResponsesClient
+
+client = OpenAIResponsesClient()
+
+text_response = client.generate_response(
+    api_key="sk-your-api-key",                 # required OpenAI API key
+    prompt="Summarize the key benefits of unit testing.",  # plain-text prompt
+    model="gpt-4o",                            # any Responses API compatible model
+    reasoning_effort="medium",                 # optional: "low" | "medium" | "high"
+    max_tokens=2000,                           # optional: caps the full response length
+)
+
+vision_response = client.generate_response(
+    api_key="sk-your-api-key",
+    prompt="Describe the main action in this image.",
+    model="gpt-4o-mini",
+    images=[
+        "/absolute/path/to/local-image.png",   # local file paths are converted to data URLs
+        "https://example.com/sample.jpg",      # remote URLs are passed through directly
+    ],
+)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | `str` | Yes | OpenAI API key used for authentication. |
+| `prompt` | `Optional[str]` | Conditional | Plain-text prompt. Required unless `images` is supplied. |
+| `model` | `str` | Yes | Target model identifier, e.g. `gpt-4o`. |
+| `max_tokens` | `int` | No | Defaults to `32000`. Passed to the Responses API as `max_output_tokens`. |
+| `reasoning_effort` | `Optional[str]` | No | For models that support reasoning hints (`"low"`, `"medium"`, `"high"`). |
+| `images` | `Optional[Sequence[str \| Path]]` | No | List of image URLs or local paths converted to data URLs. |
+
+The method returns the generated model output as a plain string.
+
+> The wrapper accepts `prompt` as plain text and translates it into the structured
+> input format expected by the Responses API.
+
+### Listing models
+
+Use `list_models` to enumerate the OpenAI models available to your account:
+
+```python
+from llmconnector import OpenAIResponsesClient
+
+client = OpenAIResponsesClient()
+for model in client.list_models(api_key="sk-your-api-key"):
+    print(model["id"], model["display_name"])
+```
+
+## LLMClient
+
+### Usage
+
+`LLMClient` routes requests to whichever provider has been registered; OpenAI, Gemini, and Anthropic are configured by default when their dependencies are available. The client also exposes `list_models` to surface the identifiers available for the selected provider.
+
+```python
+from llmconnector import LLMClient
+
+llm_client = LLMClient()
+
+response_via_router = llm_client.generate_response(
+    provider="openai",                         # selects the OpenAI wrapper
+    api_key="sk-your-api-key",
+    prompt="List three advantages of integration testing.",
+    model="gpt-4o",
+    max_tokens=1500,
+)
+
+gemini_response = llm_client.generate_response(
+    provider="gemini",                         # google-genai is installed with llmconnector
+    api_key="your-gemini-api-key",
+    prompt="Outline best practices for prompt engineering.",
+    model="gemini-2.5-flash",
+    max_tokens=1500,
+)
+
+anthropic_response = llm_client.generate_response(
+    provider="anthropic",
+    api_key="sk-ant-api-key",
+    prompt="Summarize when to rely on retrieval-augmented generation.",
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=1500,
+)
+
+# Additional providers can be registered at runtime:
+# llm_client.register_provider("custom", CustomProviderClient())
+# llm_client.generate_response(provider="custom", ...)
+```
+
+### Listing models
+
+```python
+from llmconnector import LLMClient
+
+llm_client = LLMClient()
+for model in llm_client.list_models(provider="openai", api_key="sk-your-api-key"):
+    print(model["id"], model["display_name"])
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `provider` | `str` | Yes | Registered provider key (default registry includes `'openai'`, `'gemini'`, and `'anthropic'`). |
+| `api_key` | `str` | Yes | Provider-specific API key. |
+| `prompt` | `Optional[str]` | Conditional | Plain-text prompt. Required unless `images` is supplied. |
+| `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. |
+
+Use `LLMClient.register_provider(name, client)` to add additional providers that implement
+`generate_response` with the same signature.
+
+## Development
+
+The project uses a standard `pyproject.toml` based packaging layout with sources
+stored under `src/`. Install the project in editable mode and run your preferred tooling:
+
+```bash
+pip install -e .
+```