# LLM Wrapper
A comprehensive Python wrapper for Azure OpenAI with built-in PostgreSQL integration and usage tracking. Provides detailed analytics for LLM usage with support for both text and JSON response formats, including multimodal capabilities (text + images).
## Features
- 🚀 **Easy Integration**: Simple API for interacting with Azure OpenAI services
- 📊 **Usage Tracking**: Comprehensive logging and analytics for all LLM requests
- 💾 **PostgreSQL Integration**: Built-in PostgreSQL database support with automatic table creation
- ⚡ **High Performance**: Optimized for concurrent requests and high throughput
- 🔒 **Secure**: Built-in security features and API key management
- 📈 **Analytics**: Detailed usage statistics and reporting
- 🎯 **Response Types**: Support for both text and JSON response formats
- 🖼️ **Multimodal Support**: Handle text, images, and mixed content in conversations
- 🗨️ **Conversation Support**: Multi-turn conversation capabilities with role-based messaging
- 🐳 **Production Ready**: Robust error handling and logging
## Installation
### Basic Installation
```bash
pip install hibiz-llm-wrapper
```
## Quick Start
### Basic Usage
```python
from hibiz_llm_wrapper import LLMWrapper
# Initialize the wrapper (database connection is automatic)
wrapper = LLMWrapper(
service_url="https://your-azure-openai-instance.openai.azure.com",
api_key="your-azure-openai-api-key",
deployment_name="your-deployment-name",
api_version="2023-05-15",
default_model='gpt-4'
)
# Send a text request using prompt_payload
prompt_payload = [
{"role": "user", "content": "What are the benefits of renewable energy?"}
]
response = wrapper.send_request(
prompt_payload=prompt_payload,
customer_id=1,
organization_id=1,
response_type="text",
temperature=0.7,
max_tokens=2000
)
print(f"Response: {response['processed_output']}")
print(f"Tokens used: {response['total_tokens']}")
print(f"Response type: {response['response_type']}")
# Send a JSON request
json_prompt = [
{"role": "user", "content": "Create a JSON object with information about Python programming including name, creator, and year_created."}
]
json_response = wrapper.send_request(
prompt_payload=json_prompt,
customer_id=1,
organization_id=1,
response_type="json"
)
print(f"JSON Response: {json_response['processed_output']}")
print(f"Creator: {json_response['processed_output'].get('creator', 'N/A')}")
# Get usage statistics
stats = wrapper.get_usage_stats()
print(f"Total requests: {stats['total_requests']}")
print(f"Total tokens: {stats['total_tokens']}")
# Clean up
wrapper.close()
```
### Multimodal Usage (Text + Images)
```python
# Send request with image
multimodal_prompt = [
{
"role": "user",
"content": [
{"type": "text", "text": "What do you see in this image? Describe it in detail."},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."}}
]
}
]
response = wrapper.send_request(
prompt_payload=multimodal_prompt,
customer_id=1,
organization_id=1,
response_type="text"
)
print(f"Image Analysis: {response['processed_output']}")
# Multiple images with text
multi_image_prompt = [
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two images and tell me the differences:"},
{"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
{"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}},
{"type": "text", "text": "Please provide the comparison in JSON format."}
]
}
]
comparison = wrapper.send_request(
prompt_payload=multi_image_prompt,
customer_id=1,
organization_id=1,
response_type="json"
)
```
### Multi-turn Conversations
```python
# Conversation with context
conversation_prompt = [
{"role": "user", "content": "Hello, I need help with Python programming."},
{"role": "assistant", "content": "Hello! I'd be happy to help you with Python programming. What specific topic or problem would you like assistance with?"},
{"role": "user", "content": "Can you explain list comprehensions with examples?"},
{"role": "assistant", "content": "Certainly! List comprehensions are a concise way to create lists in Python..."},
{"role": "user", "content": "Now show me how to use list comprehensions with images in the context."},
{
"role": "user",
"content": [
{"type": "text", "text": "Here's a code screenshot I'm working with:"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."}}
]
}
]
response = wrapper.send_request(
prompt_payload=conversation_prompt,
customer_id=1,
organization_id=1,
response_type="text"
)
```
## Response Types
### Text Response (Default)
```python
prompt_payload = [{"role": "user", "content": "Explain artificial intelligence"}]
response = wrapper.send_request(
prompt_payload=prompt_payload,
customer_id=1,
organization_id=1,
response_type="text"
)
# Response structure:
{
"output_text": "raw response from API",
"processed_output": "same as output_text for text responses",
"response_type": "text",
"input_tokens": 10,
"output_tokens": 150,
"total_tokens": 160,
"response_time_ms": 1200,
"model": "gpt-4",
"full_response": {...},
"original_prompt": [{"role": "user", "content": "Explain artificial intelligence"}]
}
```
### JSON Response
```python
prompt_payload = [{"role": "user", "content": "Create a JSON object with user information including name, age, and skills array"}]
response = wrapper.send_request(
prompt_payload=prompt_payload,
customer_id=1,
organization_id=1,
response_type="json"
)
# Response structure:
{
"output_text": '{"name": "John", "age": 30, "skills": ["Python", "AI"]}',
"processed_output": {"name": "John", "age": 30, "skills": ["Python", "AI"]},
"response_type": "json",
"input_tokens": 15,
"output_tokens": 25,
"total_tokens": 40,
"response_time_ms": 1500,
"model": "gpt-4",
"full_response": {...},
"original_prompt": [{"role": "user", "content": "Create a JSON object..."}]
}
```
## Prompt Payload Formats
### Simple Text Message
```python
prompt_payload = [
{"role": "user", "content": "Your question here"}
]
```
### System Message with User Input
```python
prompt_payload = [
{"role": "system", "content": "You are a helpful assistant specialized in data analysis."},
{"role": "user", "content": "Analyze this sales data for trends."}
]
```
### Multimodal Content (Text + Image)
```python
prompt_payload = [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
]
}
]
```
### Multi-turn Conversation
```python
prompt_payload = [
{"role": "user", "content": "What is machine learning?"},
{"role": "assistant", "content": "Machine learning is a subset of artificial intelligence..."},
{"role": "user", "content": "Can you give me a practical example?"}
]
```
### Complex Multimodal Conversation
```python
prompt_payload = [
{"role": "system", "content": "You are an expert image analyst and coder."},
{
"role": "user",
"content": [
{"type": "text", "text": "I have two images showing different UI designs. Please analyze them and suggest improvements:"},
{"type": "image_url", "image_url": {"url": "https://example.com/ui1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/ui2.png"}},
{"type": "text", "text": "Focus on usability and accessibility aspects."}
]
},
{"role": "assistant", "content": "I can see both UI designs. Here are my observations..."},
{
"role": "user",
"content": [
{"type": "text", "text": "Great analysis! Now here's the updated design based on your feedback:"},
{"type": "image_url", "image_url": {"url": "https://example.com/ui3.png"}},
{"type": "text", "text": "What do you think of the improvements?"}
]
}
]
```
## Database Schema
The wrapper automatically creates the following PostgreSQL table:
```sql
CREATE TABLE token_usage_log (
id SERIAL PRIMARY KEY,
customer_id INTEGER NOT NULL,
organization_id INTEGER NOT NULL,
model_name VARCHAR(255) NOT NULL,
request_params JSON,
response_params JSON,
input_tokens INTEGER NOT NULL,
output_tokens INTEGER NOT NULL,
total_tokens INTEGER NOT NULL,
request_timestamp TIMESTAMP DEFAULT NOW(),
response_time_ms INTEGER NOT NULL,
status VARCHAR(50) DEFAULT 'success'
);
```
## Usage Analytics
```python
# Get overall statistics
stats = wrapper.get_usage_stats()
# Get customer-specific statistics
customer_stats = wrapper.get_usage_stats(customer_id=1)
# Get organization-specific statistics
org_stats = wrapper.get_usage_stats(organization_id=1)
# Get statistics for a specific time period
period_stats = wrapper.get_usage_stats(
start_date="2024-01-01T00:00:00",
end_date="2024-01-31T23:59:59"
)
# Example stats output:
{
"total_requests": 150,
"total_tokens": 45000,
"models": [
{
"model_name": "gpt-4",
"requests": 100,
"input_tokens": 15000,
"output_tokens": 20000,
"total_tokens": 35000,
"avg_response_time_ms": 1200
},
{
"model_name": "gpt-3.5-turbo",
"requests": 50,
"input_tokens": 5000,
"output_tokens": 5000,
"total_tokens": 10000,
"avg_response_time_ms": 800
}
]
}
```
## Configuration Options
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `service_url` | str | Required | Azure OpenAI service endpoint URL |
| `api_key` | str | Required | Azure OpenAI API key |
| `deployment_name` | str | Required | Azure OpenAI deployment name |
| `api_version` | str | Required | Azure OpenAI API version |
| `default_model` | str | 'gpt-4' | Default model identifier |
| `timeout` | int | 30 | Request timeout in seconds |
## API Reference
### Core Methods
#### `send_request(prompt_payload, customer_id, organization_id, response_type="text", **kwargs)`
Send a request to the Azure OpenAI service using the new prompt payload format.
**Parameters:**
- `prompt_payload` (List[Dict[str, Any]]): Array of message objects with role and content
- `customer_id` (int): Customer identifier
- `organization_id` (int): Organization identifier
- `response_type` (str): Response format - "text" or "json"
- `model` (str, optional): Model to use for this request
- `temperature` (float, optional): Sampling temperature (0.0-1.0)
- `max_tokens` (int, optional): Maximum tokens in response
**Message Format:**
```python
# Text message
{"role": "user|assistant|system", "content": "text content"}
# Multimodal message
{
"role": "user|assistant|system",
"content": [
{"type": "text", "text": "text content"},
{"type": "image_url", "image_url": {"url": "image_url_or_base64"}}
]
}
```
**Returns:**
- `dict`: Response containing output text, processed output, token counts, metadata, and original prompt
#### `get_usage_stats(**filters)`
Get usage statistics with optional filtering.
**Parameters:**
- `customer_id` (int, optional): Filter by customer
- `organization_id` (int, optional): Filter by organization
- `start_date` (str, optional): Start date in ISO format
- `end_date` (str, optional): End date in ISO format
**Returns:**
- `dict`: Usage statistics including request counts, token usage, and performance metrics
#### `close()`
Close database connections and clean up resources.
## Token Calculation
The wrapper intelligently handles token calculation for different content types:
- **Text content**: Direct token counting using the specified model's tokenizer
- **Image content**: Uses placeholder tokens for estimation (actual tokens may vary based on image size and complexity)
- **Mixed content**: Combines text and image token estimates
## Error Handling
The wrapper provides comprehensive error handling:
```python
from hibiz_llm_wrapper.exceptions import APIError, DatabaseError
try:
response = wrapper.send_request(
prompt_payload=[{"role": "user", "content": "Hello"}],
customer_id=1,
organization_id=1
)
except APIError as e:
print(f"API request failed: {e}")
except DatabaseError as e:
print(f"Database operation failed: {e}")
```
## Requirements
- Python 3.8+
- Pillow (for image processing)
- tiktoken (for token counting)
## License
This project is licensed under the MIT License.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Acknowledgments
- Thanks to all contributors who have helped shape this project
- Built with love for the AI/ML community
Raw data
{
"_id": null,
"home_page": null,
"name": "hibiz-llm-wrapper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Akilan R M <akilan@hibizsolutions.com>",
"keywords": "llm, language-model, openai, azure, gpt, ai, machine-learning, database, postgresql, mysql, mongodb, usage-tracking, api-wrapper",
"author": null,
"author_email": "Akilan R M <akilan@hibizsolutions.com>",
"download_url": "https://files.pythonhosted.org/packages/1c/ab/d85c8ac5d88e43614f195d9595f6ee314c1b02fc24d159e08c1a029d475f/hibiz_llm_wrapper-1.0.2.tar.gz",
"platform": null,
"description": "# LLM Wrapper\r\n\r\nA comprehensive Python wrapper for Azure OpenAI with built-in PostgreSQL integration and usage tracking. Provides detailed analytics for LLM usage with support for both text and JSON response formats, including multimodal capabilities (text + images).\r\n\r\n## Features\r\n\r\n- \ud83d\ude80 **Easy Integration**: Simple API for interacting with Azure OpenAI services\r\n- \ud83d\udcca **Usage Tracking**: Comprehensive logging and analytics for all LLM requests\r\n- \ud83d\udcbe **PostgreSQL Integration**: Built-in PostgreSQL database support with automatic table creation\r\n- \u26a1 **High Performance**: Optimized for concurrent requests and high throughput\r\n- \ud83d\udd12 **Secure**: Built-in security features and API key management\r\n- \ud83d\udcc8 **Analytics**: Detailed usage statistics and reporting\r\n- \ud83c\udfaf **Response Types**: Support for both text and JSON response formats\r\n- \ud83d\uddbc\ufe0f **Multimodal Support**: Handle text, images, and mixed content in conversations\r\n- \ud83d\udde8\ufe0f **Conversation Support**: Multi-turn conversation capabilities with role-based messaging\r\n- \ud83d\udc33 **Production Ready**: Robust error handling and logging\r\n\r\n## Installation\r\n\r\n### Basic Installation\r\n\r\n```bash\r\npip install hibiz-llm-wrapper\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom hibiz_llm_wrapper import LLMWrapper\r\n\r\n# Initialize the wrapper (database connection is automatic)\r\nwrapper = LLMWrapper(\r\n service_url=\"https://your-azure-openai-instance.openai.azure.com\",\r\n api_key=\"your-azure-openai-api-key\",\r\n deployment_name=\"your-deployment-name\",\r\n api_version=\"2023-05-15\",\r\n default_model='gpt-4'\r\n)\r\n\r\n# Send a text request using prompt_payload\r\nprompt_payload = [\r\n {\"role\": \"user\", \"content\": \"What are the benefits of renewable energy?\"}\r\n]\r\n\r\nresponse = wrapper.send_request(\r\n prompt_payload=prompt_payload,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"text\",\r\n temperature=0.7,\r\n max_tokens=2000\r\n)\r\n\r\nprint(f\"Response: {response['processed_output']}\")\r\nprint(f\"Tokens used: {response['total_tokens']}\")\r\nprint(f\"Response type: {response['response_type']}\")\r\n\r\n# Send a JSON request\r\njson_prompt = [\r\n {\"role\": \"user\", \"content\": \"Create a JSON object with information about Python programming including name, creator, and year_created.\"}\r\n]\r\n\r\njson_response = wrapper.send_request(\r\n prompt_payload=json_prompt,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"json\"\r\n)\r\n\r\nprint(f\"JSON Response: {json_response['processed_output']}\")\r\nprint(f\"Creator: {json_response['processed_output'].get('creator', 'N/A')}\")\r\n\r\n# Get usage statistics\r\nstats = wrapper.get_usage_stats()\r\nprint(f\"Total requests: {stats['total_requests']}\")\r\nprint(f\"Total tokens: {stats['total_tokens']}\")\r\n\r\n# Clean up\r\nwrapper.close()\r\n```\r\n\r\n### Multimodal Usage (Text + Images)\r\n\r\n```python\r\n# Send request with image\r\nmultimodal_prompt = [\r\n {\r\n \"role\": \"user\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"What do you see in this image? Describe it in detail.\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...\"}}\r\n ]\r\n }\r\n]\r\n\r\nresponse = wrapper.send_request(\r\n prompt_payload=multimodal_prompt,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"text\"\r\n)\r\n\r\nprint(f\"Image Analysis: {response['processed_output']}\")\r\n\r\n# Multiple images with text\r\nmulti_image_prompt = [\r\n {\r\n \"role\": \"user\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"Compare these two images and tell me the differences:\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://example.com/image1.jpg\"}},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://example.com/image2.jpg\"}},\r\n {\"type\": \"text\", \"text\": \"Please provide the comparison in JSON format.\"}\r\n ]\r\n }\r\n]\r\n\r\ncomparison = wrapper.send_request(\r\n prompt_payload=multi_image_prompt,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"json\"\r\n)\r\n```\r\n\r\n### Multi-turn Conversations\r\n\r\n```python\r\n# Conversation with context\r\nconversation_prompt = [\r\n {\"role\": \"user\", \"content\": \"Hello, I need help with Python programming.\"},\r\n {\"role\": \"assistant\", \"content\": \"Hello! I'd be happy to help you with Python programming. What specific topic or problem would you like assistance with?\"},\r\n {\"role\": \"user\", \"content\": \"Can you explain list comprehensions with examples?\"},\r\n {\"role\": \"assistant\", \"content\": \"Certainly! List comprehensions are a concise way to create lists in Python...\"},\r\n {\"role\": \"user\", \"content\": \"Now show me how to use list comprehensions with images in the context.\"},\r\n {\r\n \"role\": \"user\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"Here's a code screenshot I'm working with:\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...\"}}\r\n ]\r\n }\r\n]\r\n\r\nresponse = wrapper.send_request(\r\n prompt_payload=conversation_prompt,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"text\"\r\n)\r\n```\r\n\r\n## Response Types\r\n\r\n### Text Response (Default)\r\n\r\n```python\r\nprompt_payload = [{\"role\": \"user\", \"content\": \"Explain artificial intelligence\"}]\r\n\r\nresponse = wrapper.send_request(\r\n prompt_payload=prompt_payload,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"text\"\r\n)\r\n\r\n# Response structure:\r\n{\r\n \"output_text\": \"raw response from API\",\r\n \"processed_output\": \"same as output_text for text responses\",\r\n \"response_type\": \"text\",\r\n \"input_tokens\": 10,\r\n \"output_tokens\": 150,\r\n \"total_tokens\": 160,\r\n \"response_time_ms\": 1200,\r\n \"model\": \"gpt-4\",\r\n \"full_response\": {...},\r\n \"original_prompt\": [{\"role\": \"user\", \"content\": \"Explain artificial intelligence\"}]\r\n}\r\n```\r\n\r\n### JSON Response\r\n\r\n```python\r\nprompt_payload = [{\"role\": \"user\", \"content\": \"Create a JSON object with user information including name, age, and skills array\"}]\r\n\r\nresponse = wrapper.send_request(\r\n prompt_payload=prompt_payload,\r\n customer_id=1,\r\n organization_id=1,\r\n response_type=\"json\"\r\n)\r\n\r\n# Response structure:\r\n{\r\n \"output_text\": '{\"name\": \"John\", \"age\": 30, \"skills\": [\"Python\", \"AI\"]}',\r\n \"processed_output\": {\"name\": \"John\", \"age\": 30, \"skills\": [\"Python\", \"AI\"]},\r\n \"response_type\": \"json\",\r\n \"input_tokens\": 15,\r\n \"output_tokens\": 25,\r\n \"total_tokens\": 40,\r\n \"response_time_ms\": 1500,\r\n \"model\": \"gpt-4\",\r\n \"full_response\": {...},\r\n \"original_prompt\": [{\"role\": \"user\", \"content\": \"Create a JSON object...\"}]\r\n}\r\n```\r\n\r\n## Prompt Payload Formats\r\n\r\n### Simple Text Message\r\n\r\n```python\r\nprompt_payload = [\r\n {\"role\": \"user\", \"content\": \"Your question here\"}\r\n]\r\n```\r\n\r\n### System Message with User Input\r\n\r\n```python\r\nprompt_payload = [\r\n {\"role\": \"system\", \"content\": \"You are a helpful assistant specialized in data analysis.\"},\r\n {\"role\": \"user\", \"content\": \"Analyze this sales data for trends.\"}\r\n]\r\n```\r\n\r\n### Multimodal Content (Text + Image)\r\n\r\n```python\r\nprompt_payload = [\r\n {\r\n \"role\": \"user\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"What's in this image?\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/jpeg;base64,...\"}}\r\n ]\r\n }\r\n]\r\n```\r\n\r\n### Multi-turn Conversation\r\n\r\n```python\r\nprompt_payload = [\r\n {\"role\": \"user\", \"content\": \"What is machine learning?\"},\r\n {\"role\": \"assistant\", \"content\": \"Machine learning is a subset of artificial intelligence...\"},\r\n {\"role\": \"user\", \"content\": \"Can you give me a practical example?\"}\r\n]\r\n```\r\n\r\n### Complex Multimodal Conversation\r\n\r\n```python\r\nprompt_payload = [\r\n {\"role\": \"system\", \"content\": \"You are an expert image analyst and coder.\"},\r\n {\r\n \"role\": \"user\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"I have two images showing different UI designs. Please analyze them and suggest improvements:\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://example.com/ui1.png\"}},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://example.com/ui2.png\"}},\r\n {\"type\": \"text\", \"text\": \"Focus on usability and accessibility aspects.\"}\r\n ]\r\n },\r\n {\"role\": \"assistant\", \"content\": \"I can see both UI designs. Here are my observations...\"},\r\n {\r\n \"role\": \"user\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"Great analysis! Now here's the updated design based on your feedback:\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://example.com/ui3.png\"}},\r\n {\"type\": \"text\", \"text\": \"What do you think of the improvements?\"}\r\n ]\r\n }\r\n]\r\n```\r\n\r\n## Database Schema\r\n\r\nThe wrapper automatically creates the following PostgreSQL table:\r\n\r\n```sql\r\nCREATE TABLE token_usage_log (\r\n id SERIAL PRIMARY KEY,\r\n customer_id INTEGER NOT NULL,\r\n organization_id INTEGER NOT NULL,\r\n model_name VARCHAR(255) NOT NULL,\r\n request_params JSON,\r\n response_params JSON,\r\n input_tokens INTEGER NOT NULL,\r\n output_tokens INTEGER NOT NULL,\r\n total_tokens INTEGER NOT NULL,\r\n request_timestamp TIMESTAMP DEFAULT NOW(),\r\n response_time_ms INTEGER NOT NULL,\r\n status VARCHAR(50) DEFAULT 'success'\r\n);\r\n```\r\n\r\n## Usage Analytics\r\n\r\n```python\r\n# Get overall statistics\r\nstats = wrapper.get_usage_stats()\r\n\r\n# Get customer-specific statistics\r\ncustomer_stats = wrapper.get_usage_stats(customer_id=1)\r\n\r\n# Get organization-specific statistics\r\norg_stats = wrapper.get_usage_stats(organization_id=1)\r\n\r\n# Get statistics for a specific time period\r\nperiod_stats = wrapper.get_usage_stats(\r\n start_date=\"2024-01-01T00:00:00\",\r\n end_date=\"2024-01-31T23:59:59\"\r\n)\r\n\r\n# Example stats output:\r\n{\r\n \"total_requests\": 150,\r\n \"total_tokens\": 45000,\r\n \"models\": [\r\n {\r\n \"model_name\": \"gpt-4\",\r\n \"requests\": 100,\r\n \"input_tokens\": 15000,\r\n \"output_tokens\": 20000,\r\n \"total_tokens\": 35000,\r\n \"avg_response_time_ms\": 1200\r\n },\r\n {\r\n \"model_name\": \"gpt-3.5-turbo\",\r\n \"requests\": 50,\r\n \"input_tokens\": 5000,\r\n \"output_tokens\": 5000,\r\n \"total_tokens\": 10000,\r\n \"avg_response_time_ms\": 800\r\n }\r\n ]\r\n}\r\n```\r\n\r\n## Configuration Options\r\n\r\n| Parameter | Type | Default | Description |\r\n|-----------|------|---------|-------------|\r\n| `service_url` | str | Required | Azure OpenAI service endpoint URL |\r\n| `api_key` | str | Required | Azure OpenAI API key |\r\n| `deployment_name` | str | Required | Azure OpenAI deployment name |\r\n| `api_version` | str | Required | Azure OpenAI API version |\r\n| `default_model` | str | 'gpt-4' | Default model identifier |\r\n| `timeout` | int | 30 | Request timeout in seconds |\r\n\r\n## API Reference\r\n\r\n### Core Methods\r\n\r\n#### `send_request(prompt_payload, customer_id, organization_id, response_type=\"text\", **kwargs)`\r\n\r\nSend a request to the Azure OpenAI service using the new prompt payload format.\r\n\r\n**Parameters:**\r\n- `prompt_payload` (List[Dict[str, Any]]): Array of message objects with role and content\r\n- `customer_id` (int): Customer identifier\r\n- `organization_id` (int): Organization identifier\r\n- `response_type` (str): Response format - \"text\" or \"json\"\r\n- `model` (str, optional): Model to use for this request\r\n- `temperature` (float, optional): Sampling temperature (0.0-1.0)\r\n- `max_tokens` (int, optional): Maximum tokens in response\r\n\r\n**Message Format:**\r\n```python\r\n# Text message\r\n{\"role\": \"user|assistant|system\", \"content\": \"text content\"}\r\n\r\n# Multimodal message\r\n{\r\n \"role\": \"user|assistant|system\", \r\n \"content\": [\r\n {\"type\": \"text\", \"text\": \"text content\"},\r\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"image_url_or_base64\"}}\r\n ]\r\n}\r\n```\r\n\r\n**Returns:**\r\n- `dict`: Response containing output text, processed output, token counts, metadata, and original prompt\r\n\r\n#### `get_usage_stats(**filters)`\r\n\r\nGet usage statistics with optional filtering.\r\n\r\n**Parameters:**\r\n- `customer_id` (int, optional): Filter by customer\r\n- `organization_id` (int, optional): Filter by organization\r\n- `start_date` (str, optional): Start date in ISO format\r\n- `end_date` (str, optional): End date in ISO format\r\n\r\n**Returns:**\r\n- `dict`: Usage statistics including request counts, token usage, and performance metrics\r\n\r\n#### `close()`\r\n\r\nClose database connections and clean up resources.\r\n\r\n## Token Calculation\r\n\r\nThe wrapper intelligently handles token calculation for different content types:\r\n\r\n- **Text content**: Direct token counting using the specified model's tokenizer\r\n- **Image content**: Uses placeholder tokens for estimation (actual tokens may vary based on image size and complexity)\r\n- **Mixed content**: Combines text and image token estimates\r\n\r\n## Error Handling\r\n\r\nThe wrapper provides comprehensive error handling:\r\n\r\n```python\r\nfrom hibiz_llm_wrapper.exceptions import APIError, DatabaseError\r\n\r\ntry:\r\n response = wrapper.send_request(\r\n prompt_payload=[{\"role\": \"user\", \"content\": \"Hello\"}],\r\n customer_id=1,\r\n organization_id=1\r\n )\r\nexcept APIError as e:\r\n print(f\"API request failed: {e}\")\r\nexcept DatabaseError as e:\r\n print(f\"Database operation failed: {e}\")\r\n```\r\n\r\n## Requirements\r\n\r\n- Python 3.8+\r\n- Pillow (for image processing)\r\n- tiktoken (for token counting)\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## Acknowledgments\r\n\r\n- Thanks to all contributors who have helped shape this project\r\n- Built with love for the AI/ML community\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python wrapper for Large Language Models with database integration and usage tracking",
"version": "1.0.2",
"project_urls": null,
"split_keywords": [
"llm",
" language-model",
" openai",
" azure",
" gpt",
" ai",
" machine-learning",
" database",
" postgresql",
" mysql",
" mongodb",
" usage-tracking",
" api-wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1eff45f854fb233b60a3f4745b474f8105027cac170daea4d451c7d3fe08a6c9",
"md5": "033f8a8061d24a842a6a78ec23a5105d",
"sha256": "5608f92f8aa33d2576a27323695ee80e5b03c5e8d2f63328a6d071d245adce27"
},
"downloads": -1,
"filename": "hibiz_llm_wrapper-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "033f8a8061d24a842a6a78ec23a5105d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13209,
"upload_time": "2025-07-25T05:21:18",
"upload_time_iso_8601": "2025-07-25T05:21:18.066830Z",
"url": "https://files.pythonhosted.org/packages/1e/ff/45f854fb233b60a3f4745b474f8105027cac170daea4d451c7d3fe08a6c9/hibiz_llm_wrapper-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1cabd85c8ac5d88e43614f195d9595f6ee314c1b02fc24d159e08c1a029d475f",
"md5": "de9e6afbbbec1424a43962d81879a2de",
"sha256": "201ccdea68080145158a420398b6c5127d6d10c9dbcfb0aa5f2ae270d2c97350"
},
"downloads": -1,
"filename": "hibiz_llm_wrapper-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "de9e6afbbbec1424a43962d81879a2de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20389,
"upload_time": "2025-07-25T05:21:20",
"upload_time_iso_8601": "2025-07-25T05:21:20.851621Z",
"url": "https://files.pythonhosted.org/packages/1c/ab/d85c8ac5d88e43614f195d9595f6ee314c1b02fc24d159e08c1a029d475f/hibiz_llm_wrapper-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 05:21:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hibiz-llm-wrapper"
}
JSON