Metadata-Version: 2.4
Name: ehs-llm-client
Version: 0.1.10
Summary: Unified LLM client. Currently supports Openai, Azure Openai and Google Gemini
Author-email: Andersen Huang <andersen.huang@ehsanalytics.com>
License-Expression: MIT
Description-Content-Type: text/markdown
Requires-Dist: openai
Requires-Dist: google-genai
Requires-Dist: python-dotenv
Requires-Dist: python-dateutil

# llm-client

[![PyPI version](https://img.shields.io/pypi/v/llm-client)](https://pypi.org/project/llm-client/)  
[![Python Version](https://img.shields.io/pypi/pyversions/llm-client)](https://www.python.org/downloads/)  

`ehs-llm-client` is a unified **async Python client** for interacting with multiple LLM providers, including **OpenAI**, **Azure OpenAI**, and **Google Gemini**.  
It supports **single calls**, **structured JSON outputs**, and **batch processing**, designed for **production-ready, reusable code** in applications, scripts, or pipelines.

---

## Features

- Async support for multiple LLM providers  
- Unified interface across OpenAI, Azure, and Google Gemini  
- Structured JSON responses via schemas  
- Retry and timeout handling  
- Batch processing support  
- Environment variable configuration for API keys  
- Easy integration into existing projects or monorepos  

---

## Installation

```bash
# Install from PyPI
pip install ehs-llm-client
```

Or install editable version during development:

```bash
# From project root
pip install -e .
```

---

## Configuration

`ehs-llm-client` supports **three configuration modes**:

### 1️⃣ Config file (`.cfg`)

Example: `llmconfig.cfg`

```ini
[default_settings]
provider = openai
model = gpt-4.1-mini

[prod]
provider = openai
model = gpt-4.1
model_batch = gpt-4.1-mini
```

Usage:

```python
from ehs_llm_client import LLM

llm = LLM("prod", config_file_path="llmconfig.cfg")
```

---

### 2️⃣ Config dictionary (for tests / CI)

```python
from ehs_llm_client import LLM

llm = LLM(
    "default",
    config={
        "default_settings": {
            "provider": "openai",
            "model": "gpt-4.1-mini"
        }
    }
)
```

---

### 3️⃣ Environment variable fallback

```bash
export LLM_PROVIDER=openai
export LLM_MODEL=gpt-4.1-mini
export OPENAI_API_KEY=sk-...
```

```python
llm = LLM("default")
```

---

## Usage

### Single async call

```python
import asyncio
from ehs_llm_client import LLM

async def main():
    llm = LLM("prod")
    messages = [{"role": "user", "content": "Say hello in JSON"}]

    response, in_tokens, out_tokens = await llm.get_response_async(
        messages, schema="return json"
    )

    print(response)

asyncio.run(main())
```

---

### Batch request

```python
batch_line = llm.create_batch_request(
    custom_id="test1",
    messages=[{"role": "user", "content": "Give me a JSON object"}],
    schema="return json"
)

batch_id = await llm.run_batch_process([batch_line], submission_id="batch123")
status = await llm.get_batch_status(batch_id)
print(status)
```

---

## API Key Management

Keep API keys **out of code**. Recommended environment variables:

| Provider | Env var name |
|----------|-------------|
| OpenAI | `openaiAPIkey` |
| Azure OpenAI | `azure_openaiAPIkey` |
| Google Gemini | `googleAPIkey` |

---

## Development

```bash
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -e .
```

---

## License

MIT License © 2026 Your Name  
