Metadata-Version: 2.1
Name: utils_b_infra
Version: 1.5.0rc1
Summary: A collection of utility functions and classes for Python projects.
Home-page: https://github.com/Fahadukr/utils-b-infra
Author: Fahad Mawlood
Author-email: fahadukr@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: SQLAlchemy
Requires-Dist: pandas
Requires-Dist: numpy<2.0.0
Requires-Dist: openai>=1.74.0
Requires-Dist: redis
Requires-Dist: pymongo
Requires-Dist: pendulum
Requires-Dist: slack-sdk
Requires-Dist: tiktoken
Requires-Dist: google-api-python-client
Requires-Dist: google-auth-httplib2
Requires-Dist: google-auth-oauthlib
Requires-Dist: Pillow
Requires-Dist: pdf2image
Requires-Dist: pydub
Provides-Extra: translation
Requires-Dist: google-cloud-translate>=3.12.0; extra == "translation"
Requires-Dist: deepl; extra == "translation"

Collection of utility functions and classes designed to enhance Python projects.
The library is organized into several modules, including logging, cache, translation models,
client interactions, data manipulation with pandas, and general-purpose functions.

# Supported Python Versions

Python >= 3.11

## Installation

You can install `utils-b-infra` using pip:

```bash
pip install utils-b-infra
```

To include the translation utilities:

```bash
pip install utils-b-infra[translation]
````

## Structure

The library is organized into the following modules:

1. logging.py: Utilities for logging with SlackAPI and writing to a file.
2. cache.py: Utilities for caching data in memory, Redis or MongoDB.
3. ai.py: Utilities for working with AI models, such as token count, tokenization, and text generation.
4. translation.py: Utilities for working with translation APIs (Supported Google Translate and DeepL).
5. services.py: Services-related utilities, such as creating google service.
6. pandas.py: Utilities for working with pandas dataframes, (df cleaning, insertion into databases...).
7. generic.py: Miscellaneous utilities that don't fit into the other specific categories (retry, run in thread,
   validate, etc.).

## Usage

Here are few examples, for more details, please refer to the docstrings in the source code.

Logging Utilities

```python
from utils_b_infra.logging import SlackLogger

logger = SlackLogger(project_name="your-project-name", slack_token="your-slack-token", default_channel_id="channel-id")
logger.info("This is an info message")
logger.error(exc=Exception, header_message="Header message appears above the exception message in the Slack message")
```

Cache Utilities

```python
from time import sleep
from utils_b_infra.cache import Cache, CacheConfig

cache_config = CacheConfig(
   cache_type="RedisCache",
   redis_host="host",
   redis_port=6379,
   redis_password="password"
)


@cache.cached(60, namespace="test1", sliding_expiration=False)
def hello(arg1: int, arg2: str) -> dict:
   sleep(5)
   data = {
      "orders": [
         "668abd233909666c44033913",
         "668ab5167a0b54248b044b14",
         "668aad6f1cd076a89e0f4e87",
         "668ac1ff28065eadb408a9b5",
         "668ac23eb6bb7b781f069567"
      ],
      "stats": {
         "1": 10,
         "2": 22
      }
   }
   print(data)
   return data


if __name__ == "__main__":
   hello(arg1=1, arg2="test")
```

AI Utilities

`generate_ai_response` passes the model ID directly to the Responses API. It
does not maintain a model list or infer capabilities from a model's name.
Choose the model and generation settings in the application configuration.
`reasoning_effort`, `verbosity`, `temperature` and `max_output_tokens` are sent
only when explicitly provided. Unsupported settings produce the original API
error immediately; they are not silently discarded or retried unchanged.

```python
from utils_b_infra.ai import TextGenerator
from openai import OpenAI
text_generator = TextGenerator(openai_client=OpenAI(api_key='your-openai-api-key'))

response = text_generator.generate_ai_response(
    prompt="Generate a professional email to a client based on the following text. Return JSON with 'subject' and 'body' fields.",
    user_text="Dear Client, we are pleased to inform you about our new services...",
    gpt_model='gpt-5',
    verbosity="medium",
    reasoning_effort="high",
    json_mode=True
)
print(response)
```

For a model that supports sampling, pass `temperature` explicitly and omit
`reasoning_effort` unless the model supports the combination. The API validates
the options; no model catalog lookup or extra discovery request is needed.

When upgrading from 1.4.x, omitted generation options now use the model's API
defaults. To preserve the previous wrapper settings, explicitly supply
`temperature=0.5` for sampling calls, or `reasoning_effort="medium"` and
`verbosity="medium"` where supported. An explicit `max_output_tokens` is now
honored for every model and includes reasoning tokens as well as visible text.
The return type, JSON parsing and `store=False` default are unchanged.

Review calls that supplied `temperature` to reasoning models: older releases
silently ignored that argument, while this release sends it and lets the API
validate it. Remove unwanted arguments before upgrading those applications.
Version `1.5.0rc1` is a prerelease so consumers can opt in individually, without
changing ordinary stable-version installs. Pin the chosen version per service.

Services Utilities

```python
from utils_b_infra.services import get_google_service

google_sheet_service = get_google_service(
   google_token_path='common/google_token.json',
   google_credentials_path='common/google_credentials.json',
   service_name='sheets'
)
```

Pandas Utilities

```python
import pandas as pd
from utils_b_infra.pandas import clean_dataframe, insert_df_into_db_in_chunks

from connections import sqlalchemy_client  # Your database connection client

df = pd.read_csv("data.csv")
clean_df = clean_dataframe(df)
with sqlalchemy_client.connect() as db_connection:
    insert_df_into_db_in_chunks(
        df=clean_df,
        table_name="table_name",
        conn=db_connection,
        if_exists='append',
        truncate_table=True,
        index=False,
        dtype=None,
        chunk_size=20_000
    )
```

Translation Utilities
To use the translation utilities, you need to install the translation extras and set up the necessary environment
variables for Google Translate:

```bash
pip install utils-b-infra[translation]
```

```python
import os
from utils_b_infra.translation import TextTranslator

# Set up Google Cloud credentials
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'path/to/google_service_account.json'

deepl_api_key = 'your-deepl-api-key'
languages = {
   'ru': 'https://ru.example.com',
   'ar': 'https://ar.example.com',
   'de': 'https://de.example.com',
   'es': 'https://es.example.com',
   'fr': 'https://fr.example.com',
   'uk': 'https://ua.example.com'
}
google_project_id = 'your-google-project-id'

translator = TextTranslator(deepl_api_key=deepl_api_key, languages=languages, google_project_id=google_project_id)

text_to_translate = "Hello, world!"
translations = translator.get_translations(
   text=text_to_translate,
   source_language="en",
   target_langs=["ru", "ar", "de"],
   engine="google"
)

for lang, translated_text in translations.items():
   print(f"{lang}: {translated_text}")
```

Generic Utilities

```python
from utils_b_infra.generic import retry_with_timeout, validate_numeric_value, run_threaded, Timer


@retry_with_timeout(retries=3, timeout=5)
def fetch_data(arg1, arg2):
    # function logic here
    pass


with Timer() as t:
    fetch_data("arg1", "arg2")
print(t.seconds_taken)  # Output: Time taken to run fetch_data function (in seconds)
print(t.minutes_taken)  # Output: Time taken to run fetch_data function (in minutes)

run_threaded(fetch_data, arg1="arg1", arg2="arg2")

is_valid = validate_numeric_value(123)
print(is_valid)  # Output: True
```

## License

This project is licensed under the MIT License. See the LICENSE file for details.



# Changelog

[1.5.0rc1] - 2026-10-30

- Remove model-name routing from `TextGenerator.generate_ai_response`. Pass model
  IDs unchanged and send reasoning, verbosity, temperature and token limits only
  when explicitly supplied. New models no longer require library changes.
- Use a consistent developer message for the prompt instead of choosing its role
  from the model name. Preserve prompt-only calls, JSON parsing and `store=False`.
- Generation options now use API defaults when omitted. Specify
  `temperature=0.5`, `reasoning_effort="medium"` or `verbosity="medium"` explicitly
  when the previous wrapper defaults are required and supported by the model.
- Honor explicit `max_output_tokens` for reasoning requests as well as sampling
  requests. This limit includes reasoning tokens.
- Propagate non-retryable API errors immediately, preserving their original type
  and details. Retain retries for transient errors and other existing failures.
- Stage the new behavior as a prerelease. Consumers must explicitly opt in;
  ordinary installs of stable releases should not change generation defaults.

[1.4.3] - 2026-05-08

- Normalize transcription audio inputs to mono MP3 before sending them to OpenAI.

[1.3.2] - 2025-08-22

- Add support for gpt-5 models in `ai.TextGenerator` class.

[1.1.0] - 2025-04-16

- Add support for processing audio files in `ai.TextGenerator`;

[1.0.0] - 2025-04-11

- Add support for processing files in the `ai.TextGenerator` class (both url and local file)
- Rename `parse_json_response` to `json_mode` in `ai.TextGenerator.generate_ai_response` - breaks older versions
- Rename `error_additional_data` to `context_data` in `logging.SlackLogger.error()` - breaks older versions
- Add support for `context_data` in `SlackLogger.info`, `logging.SlackLogger.warning` and `SlackLogger.debug`

[0.8.0] - 2025-04-01

- Add support for Slack message levels and prefixes

[0.7.0] - 2025-03-29

- Changed slack_channel_id to default_channel_id in `SlackApi` and `SlackLogger` classes.
- Updated `SlackApi` and `SlackLogger` to enable specifying custom Slack channel IDs for messages.
- Improved encapsulation in the logging classes.

[0.6.0] - 2025-02-18

- Switch the default cache database in MongoDB from the connection string to the database parameter.
- Switch the default embedding model to 'text-embedding-3-small'.
- Added support for reasoning modules with the reasoning_effort parameter in the ai.TextGenerator class.

[0.5.0] - 2024-07-30

### updated

- Switch cache mechanism from async to sync

[0.4.0] - 2024-07-20

### Added

- Caching modules

[0.3.0] - 2024-06-27

### Changed

Split the library into main and extra modules, including optional translation utilities.

## [0.2.0] - 2024-06-26:

### Added

- Support for `google-cloud-translate` V3 API.
- Support for OpenAI modules `gpt-4o` and `gpt-4o-2024-05-13` in `ai.calculate_openai_price`

### Fixed

- Issue with json parsing in `ai.TextGenerator.get_ai_response`.

### Changed

- Default openai model to `gpt-4o` in `ai.TextGenerator.get_ai_response`.
- Updated Readme file with more examples.

## [0.1.0] - 2024-06-25 initial release

### Added

- Initial release of the package.
