# Utility functions and classes

Module defining public utility functions and classes of the framework.

### contextgem.public.utils.image_to_base64(source)

Converts an image to its Base64 encoded string representation.

Helper function that can be used when constructing `Image` objects.

* **Parameters:**
  **source** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) | [`typing.BinaryIO`](https://docs.python.org/3/library/typing.html#typing.BinaryIO) | [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)) – The image source - can be a file path (str or Path),
  file-like object (BytesIO, file handle, etc.), or raw bytes data.
* **Returns:**
  A Base64 encoded string representation of the image.
* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)
* **Raises:**
  * [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError) – If the image file path does not exist.
  * [**OSError**](https://docs.python.org/3/builtins/exceptions.html#OSError) – If the image cannot be read.

Example:
: ```pycon
  >>> from pathlib import Path
  >>> import io
  >>>
  >>> # From file path
  >>> base64_str = image_to_base64("path/to/image.jpg")
  >>>
  >>> # From file handle
  >>> with open("image.png", "rb") as f:
  ...     base64_str = image_to_base64(f)
  >>>
  >>> # From bytes data
  >>> with open("image.webp", "rb") as f:
  ...     image_bytes = f.read()
  >>> base64_str = image_to_base64(image_bytes)
  >>>
  >>> # From BytesIO
  >>> buffer = io.BytesIO(image_bytes)
  >>> base64_str = image_to_base64(buffer)
  ```

### contextgem.public.utils.create_image(source)

Creates an Image instance from various image sources.

This function automatically determines the MIME type and converts the image to base64
format using Pillow functionality. It supports common image formats including JPEG,
PNG, and WebP.

* **Parameters:**
  **source** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) | `PIL.Image.Image` | [`typing.BinaryIO`](https://docs.python.org/3/library/typing.html#typing.BinaryIO) | [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)) – The image source - can be a file path (str or Path), PIL Image object,
  file-like object (BytesIO, file handle, etc.), or raw bytes data.
* **Returns:**
  An Image instance with the appropriate MIME type and base64 data.
* **Return type:**
  [`contextgem.public.images.Image`](https://contextgem.shcherbak.ai/api/images/index.html.md#contextgem.public.images.Image)
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the image format is not supported or cannot be determined.
  * [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError) – If the image file path does not exist.
  * [**OSError**](https://docs.python.org/3/builtins/exceptions.html#OSError) – If the image cannot be opened or processed.

Example:
: ```pycon
  >>> from pathlib import Path
  >>> from PIL import Image as PILImage
  >>> import io
  >>>
  >>> # From file path
  >>> img = create_image("path/to/image.jpg")
  >>>
  >>> # From PIL Image object
  >>> pil_img = PILImage.open("path/to/image.png")
  >>> img = create_image(pil_img)
  >>>
  >>> # From file-like object
  >>> with open("image.jpg", "rb") as f:
  ...     img = create_image(f)
  >>>
  >>> # From bytes data
  >>> with open("image.png", "rb") as f:
  ...     image_bytes = f.read()
  >>> img = create_image(image_bytes)
  >>>
  >>> # From BytesIO
  >>> buffer = io.BytesIO(image_bytes)
  >>> img = create_image(buffer)
  ```

### contextgem.public.utils.reload_logger_settings()

Reloads logger settings from environment variables.

This function should be called when environment variables related to logging
have been changed after the module was imported. It re-reads the environment
variables and reconfigures the logger accordingly.

* **Returns:**
  None

Example:
: ```python
  import os
  <br/>
  from contextgem import reload_logger_settings
  <br/>
  <br/>
  # Initial logger settings are loaded from environment variables at import time
  <br/>
  # Change logger level to WARNING
  os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "WARNING"
  print("Setting logger level to WARNING")
  reload_logger_settings()
  # Now the logger will only show WARNING level and above messages
  <br/>
  # Disable the logger completely
  os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "OFF"
  print("Disabling the logger")
  reload_logger_settings()
  # Now the logger is disabled and won't show any messages
  <br/>
  # You can re-enable the logger by setting it back to a valid level
  # os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "INFO"
  # reload_logger_settings()
  ```

### *class* contextgem.public.utils.JsonObjectClassStruct(\*args, \*\*kwargs)

Bases: `_JsonObjectClassStruct`

A base class that automatically converts class hierarchies to dictionary representations.

This class enables the use of existing class hierarchies (such as dataclasses or Pydantic models)
with nested type hints as a structure definition for JsonObjectConcept. When you need to use
typed class hierarchies with JsonObjectConcept, inherit from this class in all parts of your
class structure.

Example:
: ```python
  from dataclasses import dataclass
  <br/>
  from contextgem import JsonObjectClassStruct, JsonObjectConcept
  <br/>
  <br/>
  @dataclass
  class Address(JsonObjectClassStruct):
      street: str
      city: str
      country: str
  <br/>
  <br/>
  @dataclass
  class Contact(JsonObjectClassStruct):
      email: str
      phone: str
      address: Address
  <br/>
  <br/>
  @dataclass
  class Person(JsonObjectClassStruct):
      name: str
      age: int
      contact: Contact
  <br/>
  <br/>
  # Use the class structure with JsonObjectConcept
  # JsonObjectClassStruct enables automatic conversion of typed class hierarchies
  # into the dictionary structure required by JsonObjectConcept, preserving the
  # type information and nested relationships between classes.
  JsonObjectConcept(name="person", description="Person information", structure=Person)
  ```

Replacement for `__new__` that blocks direct instantiation of the
decorated class while allowing subclasses to instantiate normally.

If invoked for the exact decorated class, an error is logged and
`TypeError` is raised. For subclasses, the call is forwarded to the
next `__new__` in the MRO, preserving base-class behavior (e.g.,
Pydantic’s `BaseModel.__new__`).

* **Parameters:**
  * **inner_cls** – The class being instantiated (decorated class or
    its subclass).
  * **args** – Positional constructor arguments.
  * **kwargs** – Keyword constructor arguments.
* **Returns:**
  A new instance when called for a subclass.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – When attempting to instantiate the decorated class
  directly.
* **Return type:**
  Any