Metadata-Version: 2.4
Name: llm-hub-sdk
Version: 0.0.4
Summary: This Python SDK that provides convenient clients for interacting with the LLM-HUB – a centralized backend service
Author: NTV360
License: LICENSE
        
        Copyright (c) 2025 NTV360. All Rights Reserved.
        
        This software, including all accompanying files and documentation (collectively, the "Software"), is the proprietary property of NTV360 ("Licensor") and is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties.
        
        **NOTICE TO USER:**
        
        This Software is licensed, not sold. This license only gives you some rights to use the Software. NTV360 reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the Software only as expressly permitted in this license agreement.
        
        This Software is proprietary and confidential. Unauthorized copying, use, modification, or distribution of this Software, or any portion of it, is strictly prohibited.
        
        **RESTRICTIONS:**
        
        Without prior written consent from NTV360, you may NOT:
        
        1.  Copy, modify, adapt, translate, or create derivative works based on the Software.
        2.  Rent, lease, sublicense, assign, or transfer your rights in the Software, or authorize all or any portion of the Software to be copied onto another user's computer.
        3.  Reverse engineer, decompile, disassemble, or otherwise attempt to discover the source code of the Software, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.
        4.  Use the Software for any unlawful purpose or in any manner that violates any applicable laws or regulations.
        5.  Remove or alter any copyright notices, trademarks, or other proprietary notices on any copies of the Software.
        
        **NO WARRANTIES:**
        
        THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. NTV360 DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
        
        **LIMITATION OF LIABILITY:**
        
        IN NO EVENT SHALL NTV360 BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF NTV360 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN ANY CASE, NTV360'S ENTIRE LIABILITY UNDER ANY PROVISION OF THIS AGREEMENT SHALL BE LIMITED TO THE AMOUNT ACTUALLY PAID BY YOU FOR THE SOFTWARE, IF ANY.
        
        **GOVERNING LAW:**
        
        This agreement shall be governed by and construed in accordance with the laws of the Republic of the Philippines, without regard to its conflict of law provisions. Any legal action or proceeding arising under or in connection with this agreement will be brought exclusively in the courts of competent jurisdiction located in Cebu City, Philippines, and the parties hereby irrevocably consent to the exclusive jurisdiction and venue of such courts.
        
        For licensing inquiries, or if you wish to request permission to use the Software in a manner not expressly permitted herein, please contact NTV360.
        
        By installing, copying, or otherwise using the Software, you acknowledge that you have read this license agreement, understand it, and agree to be bound by its terms and conditions. If you do not agree to the terms of this license, do not install or use the Software.
        
Keywords: llm,hub,sdk,api,chat,generative-ai
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: requests>=2.32.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Requires-Dist: docutils!=0.21.post1,>=0.21; extra == "dev"
Dynamic: license-file

This Python SDK that provides convenient clients for interacting with the **LLM-HUB** – a centralized backend service. Your Python applications can use this SDK to send chat completion requests to the LLM-HUB, which manages and routes these requests to its integrated LLM providers and their models (e.g., models from Anthropic, Google's Gemini, and OpenAI).

**Note:** This SDK communicates with _your specific LLM-HUB API_, not directly with the individual LLM providers. Your LLM-HUB service handles the authentication and interaction with the final LLM APIs it manages.

## Features

- Provider-specific clients (`GeminiClient`, `OpenAIClient`, `AnthropicClient`) for clear usage when targeting specific provider capabilities through the LLM-HUB.
- Handles communication with the LLM-HUB's chat endpoint (typically `/v1/chat`).
- Configuration of the LLM-HUB API URL via environment variables (`CHAT_API_BASE_URL`).
- Optional authentication with the LLM-HUB API via environment variables (`SDK_CHAT_API_KEY`) or direct initialization.
- Built-in custom exceptions (`APIRequestError`, `ConnectionError`, `TimeoutError`, `SDKError`) for easier error handling.
- Based on the robust `requests` library for HTTP communication.

<!-- Project Structure section is omitted as it's less relevant for SDK users -->

## Getting Started

### Prerequisites

- Python 3.8+
- `pip` package manager
- Access to a running instance of your LLM-HUB API that this SDK is designed to talk to.

### Installation

1.  **Set up a Virtual Environment (Recommended):**
    It's highly recommended to use a virtual environment to manage your project's dependencies and avoid conflicts with other Python projects.

        - **Create the virtual environment:**
          Open your terminal or command prompt in your project's root directory and run:

          ```bash
          python -m venv .venv
          # Or, if you have multiple Python versions, you might use:
          # python3 -m venv .venv
          # On Windows, you can also use the py launcher:
          # py -m venv .venv
          ```

          This will create a directory named `.venv` (or your chosen name) containing the virtual environment.

        - **Activate the virtual environment:**
          You need to activate the environment in each new terminal session where you want to use it.

          - **On Windows (Command Prompt or PowerShell):**
            ```bash
            .venv\Scripts\activate
            ```
          - **On macOS and Linux (bash/zsh):**
            `bash

    source .venv/bin/activate
    `        Once activated, your terminal prompt will usually change to indicate that you are in the virtual environment (e.g.,`(.venv) Your-User@Your-Machine:...$`).

2.  **Install the SDK:**
    With your virtual environment activated, you can now install the SDK.

    ```bash
    pip install llm-unified-sdk  # Replace llm-unified-sdk with your actual package name
    ```

    This will automatically install the required `requests` library within your active virtual environment.

3.  **(Optional) Install `python-dotenv`:**
    If you plan to manage configuration using a `.env` file in your application, install `python-dotenv` into your virtual environment:
    ```bash
    pip install python-dotenv
    ```

## Configuration

The SDK needs to know the URL of your LLM-HUB API. This is typically configured in the environment of the application _using_ the SDK.

1.  **Create a `.env` file** in the root directory of _your application project_:

    ```dotenv
    # .env file for YOUR application

    # REQUIRED: The full base URL of your running LLM-HUB API
    # Example: CHAT_API_BASE_URL="http://localhost:8000"
    # Example: CHAT_API_BASE_URL="https://your-llm-hub-api.com"
    CHAT_API_BASE_URL="YOUR_LLM_HUB_API_URL_HERE"

    # OPTIONAL: API key required BY YOUR LLM-HUB API itself (if it's protected)
    # The SDK will use this as a fallback if no api_key is passed during init.
    # Leave blank or omit if your LLM-HUB doesn't require a key from clients.
    # SDK_CHAT_API_KEY="YOUR_LLM_HUB_API_ACCESS_KEY_HERE"
    ```

2.  **Load the `.env` file** in your application code _before_ initializing the SDK client:

    ```python
    from dotenv import load_dotenv
    import os

    load_dotenv() # Loads variables from .env into the environment

    # Retrieve the base URL for the SDK
    api_url = os.getenv("CHAT_API_BASE_URL")

    if not api_url:
        print("Error: CHAT_API_BASE_URL is not set in the environment!")
        # Handle error appropriately
    ```

## Usage Example

This section guides you through using the SDK to send chat completion requests to your LLM-HUB. We'll start with a basic setup and then show how to make it more dynamic.

**Prerequisites:**

- You have completed the "Getting Started" and "Configuration" sections.
- Your `.env` file is in your project root, with `CHAT_API_BASE_URL` pointing to your LLM-HUB.
- Create a Python file for your application, e.g., `app.py`.

### 1. Basic Setup: Imports and Configuration

First, import the necessary modules and load your LLM-HUB configuration.

```python
# app.py
import os
import logging
import json # For pretty-printing responses
from dotenv import load_dotenv

# Import your SDK package
# If your package is named 'llm_unified_sdk', use:
# import llm_unified_sdk as SDK
import llm_hub_sdk # Make sure this matches your SDK's import name

# Load environment variables from .env
load_dotenv()

# Configure basic logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

# Get the LLM-HUB API URL from environment
API_URL = os.getenv("CHAT_API_BASE_URL")
if not API_URL:
    logging.error("FATAL: CHAT_API_BASE_URL (LLM-HUB URL) not set. Please create a .env file or set the environment variable.")
    exit(1)


logging.info(f"LLM-HUB URL set to: {API_URL}")
```

This sets up essential imports, loads your .env configuration, and verifies that CHAT_API_BASE_URL is available.

2. Initializing a Specific Client
   - The SDK uses provider-specific clients (e.g., OpenAIClient, GeminiClient) to help your LLM-HUB route requests correctly.
   - Let's initialize an OpenAIClient to interact with an OpenAI-compatible model available through your LLM-HUB.

```python
# app.py (continued)

# Import the specific client and its exceptions
# (Assumes SDK.openai.OpenAIClient and its exceptions exist)
try:
    from SDK.openai import OpenAIClient
    # Import specific exceptions for targeted error handling
    from SDK.openai import APIRequestError, ConnectionError, TimeoutError, SDKError as OpenAI_SDKError
except ImportError:
    logging.error("Could not import OpenAIClient or its exceptions. Ensure SDK is structured correctly.")
    exit(1) # INDENTED if it belongs to the except block

# Define the model identifier known to YOUR LLM-HUB
# This tells the LLM-HUB which underlying model to use (e.g., "gpt-4o", "your-custom-openai-model-id")
TARGET_MODEL_ID = "gpt-4o" # Example: an OpenAI model identifier

try: # Initialize the client for your LLM-HUB
    # VV INDENTED LINES BELOW VV
    chat_client = OpenAIClient(
        base_url=API_URL,       # Your LLM-HUB's URL
        model=TARGET_MODEL_ID,  # The model identifier for the LLM-HUB
        # api_key="YOUR_HUB_KEY"  # Optional: Pass API key directly. If used, uncomment and place on its own line.
                                # Or ensure it's picked from SDK_CHAT_API_KEY in .env
    )
    logging.info(f"OpenAIClient initialized for model '{TARGET_MODEL_ID}' via LLM-HUB.")
except (ValueError, TypeError) as e:
    # VV INDENTED LINES BELOW VV
    logging.error(f"Failed to initialize OpenAIClient: {e}")
    exit(1)
```

- We import OpenAIClient and its specific exceptions.
- TARGET_MODEL_ID is the name/ID your LLM-HUB uses to identify the target model.
- The client is initialized with your LLM-HUB's base_url and the model ID.

## License

Copyright (c) 2025 NTV360. All rights reserved.

This software is proprietary and is distributed without any license granting rights to use, copy, modify, or distribute. Use of this software requires specific permission from the copyright holder. Please refer to the NOTICE file (if provided) or contact the copyright holder for terms of use.
