c1groupy 0.3.0__tar.gz → 0.4.2__tar.gz

c1groupy-0.3.0/README.md → c1groupy-0.4.2/PKG-INFO

@@ -1,4 +1,35 @@
+Metadata-Version: 2.4
+Name: c1groupy
+Version: 0.4.2
+Summary: C1G company Python module for utilities and project setup
+License-Expression: MIT
+License-File: LICENCE
+Author: Tim M Schendzielorz
+Author-email: tim.schendzielorz@googlemail.com
+Requires-Python: >=3.12, <4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: argon2-cffi (>=23.0.0,<24.0.0)
+Requires-Dist: google-api-python-client (>=2.0.0,<3.0.0)
+Requires-Dist: google-auth (>=2.0.0,<3.0.0)
+Requires-Dist: google-cloud-logging (>=3.0.0,<4.0.0)
+Requires-Dist: google-cloud-secret-manager (>=2.0.0,<3.0.0)
+Requires-Dist: google-cloud-storage (>=2.0.0,<3.0.0)
+Requires-Dist: httpx[http2] (>=0.27.0,<1.0.0)
+Requires-Dist: langchain (>=0.3.0,<1.0.0)
+Requires-Dist: langchain-anthropic (>=0.2.0,<1.0.0)
+Requires-Dist: langchain-core (>=0.3.0,<1.0.0)
+Requires-Dist: langchain-google-genai (>=2.0.0,<3.0.0)
+Requires-Dist: langchain-openai (>=0.2.0,<1.0.0)
+Requires-Dist: langfuse (>=3.6.1,<4.0.0)
+Requires-Dist: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: rich (>=13.0.0,<14.0.0)
+Description-Content-Type: text/markdown
+
 # c1gpy
+[![Publish to PyPI](https://github.com/Career1Group/c1gpy/actions/workflows/publish_package.yaml/badge.svg)](https://github.com/Career1Group/c1gpy/actions/workflows/publish_package.yaml)
 
 C1G company Python module for utilities and project setup.
 
@@ -13,7 +44,7 @@ pip install c1groupy
 Or with uv:
 
 ```bash
-uv pip install c1groupy
+uv add c1groupy
 ```
 
 ## Features
@@ -574,6 +605,116 @@ client.delete_content("document_id", start_index=1, end_index=10)
 
 ---
 
+## 6. LLM Handler
+
+Unified interface for calling LLMs (OpenAI, Anthropic, Google Gemini) with:
+
+- **Langfuse** prompt management (prompt fetch + compilation)
+- **Tracing** via Langfuse callback handler
+- **Sync + async** calls
+- **Batch** calls
+- **Streaming** responses
+
+### Basic usage
+
+```python
+from c1gpy.llm_handler import LangfuseConfig, LLMHandler
+
+langfuse_config = LangfuseConfig(
+    secret_key="sk-lf-...",
+    public_key="pk-lf-...",
+    host="https://cloud.langfuse.com",
+)
+
+handler = LLMHandler(
+    model_name="gpt-4o",
+    api_key="sk-...",
+    langfuse_prompt_name="my-prompt",
+    langfuse_config=langfuse_config,
+)
+
+result = handler.call_model(keyword="test")
+```
+
+### Reusing a single Langfuse client (recommended)
+
+If you create multiple `LLMHandler` instances in the same service, reuse a single
+Langfuse client:
+
+```python
+from c1gpy.llm_handler import LangfuseConfig, LLMHandler, get_langfuse_client
+
+langfuse_config = LangfuseConfig(
+    secret_key="sk-lf-...",
+    public_key="pk-lf-...",
+    host="https://cloud.langfuse.com",
+)
+
+langfuse = get_langfuse_client(langfuse_config)
+
+handler_1 = LLMHandler(
+    model_name="gpt-4o",
+    api_key="sk-...",
+    langfuse_prompt_name="my-prompt",
+    langfuse_config=langfuse_config,
+    langfuse=langfuse,
+)
+
+handler_2 = LLMHandler(
+    model_name="gpt-4o-mini",
+    api_key="sk-...",
+    langfuse_prompt_name="my-other-prompt",
+    langfuse_config=langfuse_config,
+    langfuse=langfuse,
+)
+```
+
+### Async
+
+```python
+result = await handler.acall_model(keyword="test")
+```
+
+### Batch
+
+```python
+results = handler.batch_invoke(
+    [{"keyword": "a"}, {"keyword": "b"}, {"keyword": "c"}]
+)
+
+results_async = await handler.abatch_invoke(
+    [{"keyword": "a"}, {"keyword": "b"}, {"keyword": "c"}]
+)
+```
+
+### Streaming
+
+```python
+for chunk in handler.call_model_stream(keyword="test"):
+    print(chunk, end="")
+
+async for chunk in handler.acall_model_stream(keyword="test"):
+    print(chunk, end="")
+```
+
+### Provider selection
+
+Providers are auto-detected from `model_name` prefixes (e.g. `gpt-*`, `claude-*`, `gemini-*`).
+You can also explicitly override the provider:
+
+```python
+from c1gpy.llm_handler import ModelProvider, LLMHandler
+
+handler = LLMHandler(
+    model_name="gpt-4o",
+    api_key="sk-...",
+    langfuse_prompt_name="my-prompt",
+    langfuse_config=langfuse_config,
+    provider=ModelProvider.OPENAI,
+)
+```
+
 ## License
 
 MIT
+

c1groupy-0.3.0/PKG-INFO → c1groupy-0.4.2/README.md

@@ -1,28 +1,5 @@
-Metadata-Version: 2.4
-Name: c1groupy
-Version: 0.3.0
-Summary: C1G company Python module for utilities and project setup
-License-Expression: MIT
-License-File: LICENCE
-Author: Tim M Schendzielorz
-Author-email: tim.schendzielorz@googlemail.com
-Requires-Python: >=3.12, <4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: argon2-cffi (>=23.0.0,<24.0.0)
-Requires-Dist: google-api-python-client (>=2.0.0,<3.0.0)
-Requires-Dist: google-auth (>=2.0.0,<3.0.0)
-Requires-Dist: google-cloud-logging (>=3.0.0,<4.0.0)
-Requires-Dist: google-cloud-secret-manager (>=2.0.0,<3.0.0)
-Requires-Dist: google-cloud-storage (>=2.0.0,<3.0.0)
-Requires-Dist: httpx[http2] (>=0.27.0,<1.0.0)
-Requires-Dist: langfuse (>=3.6.1,<4.0.0)
-Requires-Dist: rich (>=13.0.0,<14.0.0)
-Description-Content-Type: text/markdown
-
 # c1gpy
+[![Publish to PyPI](https://github.com/Career1Group/c1gpy/actions/workflows/publish_package.yaml/badge.svg)](https://github.com/Career1Group/c1gpy/actions/workflows/publish_package.yaml)
 
 C1G company Python module for utilities and project setup.
 
@@ -37,7 +14,7 @@ pip install c1groupy
 Or with uv:
 
 ```bash
-uv pip install c1groupy
+uv add c1groupy
 ```
 
 ## Features
@@ -598,7 +575,115 @@ client.delete_content("document_id", start_index=1, end_index=10)
 
 ---
 
+## 6. LLM Handler
+
+Unified interface for calling LLMs (OpenAI, Anthropic, Google Gemini) with:
+
+- **Langfuse** prompt management (prompt fetch + compilation)
+- **Tracing** via Langfuse callback handler
+- **Sync + async** calls
+- **Batch** calls
+- **Streaming** responses
+
+### Basic usage
+
+```python
+from c1gpy.llm_handler import LangfuseConfig, LLMHandler
+
+langfuse_config = LangfuseConfig(
+    secret_key="sk-lf-...",
+    public_key="pk-lf-...",
+    host="https://cloud.langfuse.com",
+)
+
+handler = LLMHandler(
+    model_name="gpt-4o",
+    api_key="sk-...",
+    langfuse_prompt_name="my-prompt",
+    langfuse_config=langfuse_config,
+)
+
+result = handler.call_model(keyword="test")
+```
+
+### Reusing a single Langfuse client (recommended)
+
+If you create multiple `LLMHandler` instances in the same service, reuse a single
+Langfuse client:
+
+```python
+from c1gpy.llm_handler import LangfuseConfig, LLMHandler, get_langfuse_client
+
+langfuse_config = LangfuseConfig(
+    secret_key="sk-lf-...",
+    public_key="pk-lf-...",
+    host="https://cloud.langfuse.com",
+)
+
+langfuse = get_langfuse_client(langfuse_config)
+
+handler_1 = LLMHandler(
+    model_name="gpt-4o",
+    api_key="sk-...",
+    langfuse_prompt_name="my-prompt",
+    langfuse_config=langfuse_config,
+    langfuse=langfuse,
+)
+
+handler_2 = LLMHandler(
+    model_name="gpt-4o-mini",
+    api_key="sk-...",
+    langfuse_prompt_name="my-other-prompt",
+    langfuse_config=langfuse_config,
+    langfuse=langfuse,
+)
+```
+
+### Async
+
+```python
+result = await handler.acall_model(keyword="test")
+```
+
+### Batch
+
+```python
+results = handler.batch_invoke(
+    [{"keyword": "a"}, {"keyword": "b"}, {"keyword": "c"}]
+)
+
+results_async = await handler.abatch_invoke(
+    [{"keyword": "a"}, {"keyword": "b"}, {"keyword": "c"}]
+)
+```
+
+### Streaming
+
+```python
+for chunk in handler.call_model_stream(keyword="test"):
+    print(chunk, end="")
+
+async for chunk in handler.acall_model_stream(keyword="test"):
+    print(chunk, end="")
+```
+
+### Provider selection
+
+Providers are auto-detected from `model_name` prefixes (e.g. `gpt-*`, `claude-*`, `gemini-*`).
+You can also explicitly override the provider:
+
+```python
+from c1gpy.llm_handler import ModelProvider, LLMHandler
+
+handler = LLMHandler(
+    model_name="gpt-4o",
+    api_key="sk-...",
+    langfuse_prompt_name="my-prompt",
+    langfuse_config=langfuse_config,
+    provider=ModelProvider.OPENAI,
+)
+```
+
 ## License
 
 MIT
-

{c1groupy-0.3.0 → c1groupy-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "c1groupy"
-version = "0.3.0"
+version = "0.4.2"
 description = "C1G company Python module for utilities and project setup"
 authors = [
     {name = "Tim M Schendzielorz",email = "tim.schendzielorz@googlemail.com"},
@@ -20,7 +20,13 @@ dependencies = [
     "google-cloud-secret-manager (>=2.0.0,<3.0.0)",
     "google-cloud-storage (>=2.0.0,<3.0.0)",
     "google-api-python-client (>=2.0.0,<3.0.0)",
-    "google-auth (>=2.0.0,<3.0.0)"
+    "google-auth (>=2.0.0,<3.0.0)",
+    "langchain (>=0.3.0,<1.0.0)",
+    "langchain-core (>=0.3.0,<1.0.0)",
+    "langchain-openai (>=0.2.0,<1.0.0)",
+    "langchain-anthropic (>=0.2.0,<1.0.0)",
+    "langchain-google-genai (>=2.0.0,<3.0.0)",
+    "pydantic (>=2.0.0,<3.0.0)"
 ]
 
 [project.scripts]
@@ -34,3 +40,9 @@ packages = [{include = "c1gpy", from = "src"}]
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+]

c1groupy-0.4.2/src/c1gpy/llm_handler/__init__.py

@@ -0,0 +1,78 @@
+"""
+LLM Handler sub-package for unified LLM interactions.
+
+This package provides a Pythonic interface for calling various LLM providers
+(OpenAI, Anthropic, Google) with integrated Langfuse prompt management and tracing.
+
+Key Features:
+    - Unified API across multiple providers (OpenAI, Anthropic, Google)
+    - Langfuse integration for prompt management and tracing
+    - Structured output support via Pydantic models
+    - JSON mode for raw dictionary responses
+    - Synchronous and asynchronous operations
+    - Streaming support
+
+Example:
+    >>> from c1gpy.llm_handler import LLMHandler, LangfuseConfig, ModelProvider
+    >>> from pydantic import BaseModel
+    >>>
+    >>> class ProductTitles(BaseModel):
+    ...     titles: list[str]
+    ...
+    >>> handler = LLMHandler(
+    ...     model_name="gpt-4o",
+    ...     api_key="sk-...",
+    ...     langfuse_prompt_name="product-title-generator",
+    ...     langfuse_config=LangfuseConfig(
+    ...         secret_key="sk-lf-...",
+    ...         public_key="pk-lf-...",
+    ...     ),
+    ...     response_model=ProductTitles,
+    ... )
+    >>>
+    >>> # Sync call
+    >>> result = handler.call_model(keywords=["laptop", "gaming"], n_titles=5)
+    >>> print(result.titles)
+    >>>
+    >>> # Async call
+    >>> result = await handler.acall_model(keywords=["laptop"], n_titles=3)
+    >>>
+    >>> # Streaming
+    >>> for chunk in handler.call_model_stream(keywords=["laptop"]):
+    ...     print(chunk, end="")
+"""
+
+from c1gpy.llm_handler.config import LangfuseConfig
+from c1gpy.llm_handler.exceptions import (
+    LLMHandlerError,
+    PromptCompilationError,
+    PromptNotFoundError,
+    ProviderError,
+    ResponseParsingError,
+)
+from c1gpy.llm_handler.langfuse_client import get_langfuse_client
+from c1gpy.llm_handler.handler import LLMHandler
+from c1gpy.llm_handler.provider_registry import (
+    ModelProvider,
+    create_llm,
+    detect_provider,
+)
+
+__all__ = [
+    # Main handler
+    "LLMHandler",
+    # Configuration
+    "LangfuseConfig",
+    # Langfuse
+    "get_langfuse_client",
+    # Providers
+    "ModelProvider",
+    "create_llm",
+    "detect_provider",
+    # Exceptions
+    "LLMHandlerError",
+    "ProviderError",
+    "PromptCompilationError",
+    "PromptNotFoundError",
+    "ResponseParsingError",
+]

c1groupy-0.4.2/src/c1gpy/llm_handler/config.py

@@ -0,0 +1,44 @@
+"""
+Configuration classes for the LLM Handler module.
+
+This module provides dataclasses for configuring the LLM handler,
+including Langfuse integration settings.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class LangfuseConfig:
+    """Configuration for Langfuse integration.
+
+    This immutable dataclass holds the credentials and settings needed
+    to connect to Langfuse for prompt management and tracing.
+
+    Args:
+        secret_key: Langfuse secret key (starts with 'sk-lf-').
+        public_key: Langfuse public key (starts with 'pk-lf-').
+        host: Langfuse API host URL. Defaults to cloud.langfuse.com.
+
+    Example:
+        >>> config = LangfuseConfig(
+        ...     secret_key="sk-lf-...",
+        ...     public_key="pk-lf-...",
+        ... )
+        >>> config.host
+        'https://cloud.langfuse.com'
+    """
+
+    secret_key: str
+    public_key: str
+    host: str = field(default="https://cloud.langfuse.com")
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if not self.secret_key:
+            raise ValueError("secret_key cannot be empty")
+        if not self.public_key:
+            raise ValueError("public_key cannot be empty")
+        if not self.host:
+            raise ValueError("host cannot be empty")
+

c1groupy-0.4.2/src/c1gpy/llm_handler/exceptions.py

@@ -0,0 +1,142 @@
+"""
+Custom exceptions for the LLM Handler module.
+
+This module defines exceptions for error handling across the LLM handler,
+including provider-related errors, prompt compilation errors, and general
+handler errors.
+"""
+
+
+class LLMHandlerError(Exception):
+    """Base exception for all LLM Handler errors.
+
+    Args:
+        message: Human-readable error description.
+
+    Example:
+        >>> raise LLMHandlerError("Failed to process LLM response")
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(self.message)
+
+
+class ProviderError(LLMHandlerError):
+    """Raised when there is an error related to the model provider.
+
+    This includes errors such as:
+    - Unknown or unsupported model provider
+    - Failed provider initialization
+    - Invalid API key for provider
+
+    Args:
+        message: Human-readable error description.
+        provider: Optional provider name that caused the error.
+
+    Example:
+        >>> raise ProviderError("Unknown model: xyz-model", provider="unknown")
+    """
+
+    def __init__(self, message: str, provider: str | None = None) -> None:
+        self.provider = provider
+        super().__init__(message)
+
+
+class PromptCompilationError(LLMHandlerError):
+    """Raised when prompt compilation fails.
+
+    This occurs when:
+    - Required template variables are missing
+    - Template syntax is invalid
+    - Langfuse prompt retrieval fails
+
+    Args:
+        message: Human-readable error description.
+        prompt_name: Optional name of the prompt that failed.
+        missing_vars: Optional list of missing template variables.
+
+    Example:
+        >>> raise PromptCompilationError(
+        ...     "Missing required variable",
+        ...     prompt_name="product-generator",
+        ...     missing_vars=["keywords"]
+        ... )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        prompt_name: str | None = None,
+        missing_vars: list[str] | None = None,
+    ) -> None:
+        self.prompt_name = prompt_name
+        self.missing_vars = missing_vars or []
+        super().__init__(message)
+
+
+class ResponseParsingError(LLMHandlerError):
+    """Raised when the LLM response cannot be parsed.
+
+    This occurs when:
+    - Response is not valid JSON when json_mode is enabled
+    - Response does not match the expected Pydantic model schema
+    - Response content is empty or malformed
+
+    Args:
+        message: Human-readable error description.
+        raw_response: Optional raw response content that failed to parse.
+
+    Example:
+        >>> raise ResponseParsingError(
+        ...     "Invalid JSON in response",
+        ...     raw_response="not valid json"
+        ... )
+    """
+
+    def __init__(self, message: str, raw_response: str | None = None) -> None:
+        self.raw_response = raw_response
+        super().__init__(message)
+
+
+class PromptNotFoundError(LLMHandlerError):
+    """Raised when a Langfuse prompt cannot be found.
+
+    This error typically occurs due to one of the following reasons:
+    - The prompt name does not exist in the Langfuse project
+    - The specified label (e.g., 'production') does not exist for the prompt
+    - The API keys (secret_key, public_key) belong to a different Langfuse project
+
+    Args:
+        prompt_name: Name of the prompt that was not found.
+        label: Label that was searched for.
+        original_error: Optional original exception from Langfuse.
+
+    Example:
+        >>> raise PromptNotFoundError(
+        ...     prompt_name="my-prompt",
+        ...     label="production",
+        ... )
+    """
+
+    def __init__(
+        self,
+        prompt_name: str,
+        label: str,
+        original_error: Exception | None = None,
+    ) -> None:
+        self.prompt_name = prompt_name
+        self.label = label
+        self.original_error = original_error
+
+        message = (
+            f"Langfuse prompt not found: '{prompt_name}' with label '{label}'.\n\n"
+            f"Please verify:\n"
+            f"  1. The prompt name '{prompt_name}' exists in your Langfuse project\n"
+            f"  2. The prompt has a version with label '{label}'\n"
+            f"  3. Your API keys (secret_key, public_key) are from the SAME Langfuse "
+            f"project where the prompt was created\n\n"
+            f"Hint: Prompts are project-scoped in Langfuse. If you created the prompt "
+            f"in a different project, you need to use that project's API keys."
+        )
+        super().__init__(message)