Images

Images#

Module for handling document images.

This module provides the Image class, which represents visual content that can be attached to or fully represent a document. Images are stored in base64-encoded format with specified MIME types to ensure proper handling.

The module supports common image formats (JPEG, PNG, WebP) and integrates with the broader ContextGem framework for document analysis that includes visual content alongside textual information.

class contextgem.public.images.Image(**data)[source]#

Bases: _InstanceBase

Represents an image with specified MIME type and base64-encoded data. An image is typically attached to a document, or fully represents a document.

Util function create_image() from contextgem.public.utils can be used to create an Image instance from various sources: file paths, PIL Image objects, file-like objects, or raw bytes data.

Variables:

  • mime_type (Literal["image/jpg", "image/jpeg", "image/png", "image/webp"]) – The MIME type of the image. This must be one of the predefined valid types (“image/jpg”, “image/jpeg”, “image/png”, “image/webp”).

  • base64_data (str) – The base64-encoded data of the image. The util function image_to_base64() from contextgem.public.utils can be used to encode images to base64.

Parameters:

  • custom_data (dict)

  • mime_type (Literal['image/jpg', 'image/jpeg', 'image/png', 'image/webp'])

  • base64_data (Annotated[str, Strict(strict=True), StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)])

Note:
  • Attached to documents:

    An image must be attached to a document. A document can have multiple images.

  • Extraction types:

    Only concept extraction is supported for images. Use LLM with role "extractor_vision" or "reasoner_vision" to extract concepts from images.

Example:
Image definition#
from pathlib import Path

from contextgem import Document, Image, create_image, image_to_base64


# Path is adapted for doc tests
current_file = Path(__file__).resolve()
root_path = current_file.parents[4]

# Using the create_image utility function (recommended approach)
image_path = root_path / "tests" / "images" / "invoices" / "invoice.jpg"
jpg_image = create_image(
    image_path
)  # Automatically detects MIME type and converts to base64

# Using pre-encoded base64 data directly
png_image = Image(
    mime_type="image/png",
    base64_data="base64-string",  # image as a base64 string
)

# Using a different supported image format with create_image
webp_image = create_image(root_path / "tests" / "images" / "invoices" / "invoice.webp")

# Alternative: Manual approach using image_to_base64 (when you need specific control)
manual_image = Image(mime_type="image/jpeg", base64_data=image_to_base64(image_path))

# Attaching an image to a document
# Documents can contain both text and multiple images, or just images

# Create a document with text content
text_document = Document(
    raw_text="This is a document with an attached image that shows an invoice.",
    images=[jpg_image],
)

# Create a document with only image content (no text)
image_only_document = Document(images=[jpg_image])

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

mime_type: Literal['image/jpg', 'image/jpeg', 'image/png', 'image/webp']#
base64_data: NonEmptyStr#
clone()#

Creates and returns a deep copy of the current instance.

Return type:

typing.Self

Returns:

A deep copy of the current instance.

classmethod from_dict(obj_dict)#

Reconstructs an instance of the class from a dictionary representation.

This method deserializes a dictionary containing the object’s attributes and values into a new instance of the class. It handles complex nested structures like aspects, concepts, and extracted items, properly reconstructing each component.

Parameters:

obj_dict (dict[str, Any]) – Dictionary containing the serialized object data.

Returns:

A new instance of the class with restored attributes.

Return type:

Self

classmethod from_disk(file_path)#

Loads an instance of the class from a JSON file stored on disk.

This method reads the JSON content from the specified file path and deserializes it into an instance of the class using the from_json method.

Parameters:

file_path (str | Path) – Path to the JSON file to load (must end with ‘.json’). Can be a string or a Path object.

Returns:

An instance of the class populated with the data from the file.

Return type:

Self

Raises:
classmethod from_json(json_string)#

Creates an instance of the class from a JSON string representation.

This method deserializes the provided JSON string into a dictionary and uses the from_dict method to construct the class instance. It validates that the class name in the serialized data matches the current class.

Parameters:

json_string (str) – JSON string containing the serialized object data.

Returns:

A new instance of the class with restored state.

Return type:

Self

Raises:

TypeError – If the class name in the serialized data doesn’t match.

to_dict()#

Transforms the current object into a dictionary representation.

Converts the object to a dictionary that includes: - All public attributes - Special handling for specific public and private attributes

When an LLM or LLM group is serialized, its API credentials and usage/cost stats are removed.

Returns:

A dictionary representation of the current object with all necessary data for serialization

Return type:

dict[str, Any]

to_disk(file_path)#

Saves the serialized instance to a JSON file at the specified path.

This method converts the instance to a dictionary representation using to_dict(), then writes it to disk as a formatted JSON file with UTF-8 encoding.

Parameters:

file_path (str | Path) – Path where the JSON file should be saved (must end with ‘.json’). Can be a string or a Path object.

Return type:

None

Returns:

None

Raises:

  • ValueError – If the file path doesn’t end with ‘.json’.

  • RuntimeError – If there’s an error during the file writing process.

to_json()#

Converts the object to its JSON string representation.

Serializes the object into a JSON-formatted string using the dictionary representation provided by the to_dict() method.

Returns:

A JSON string representation of the object.

Return type:

str

property unique_id: str#

Returns the ULID of the instance.

custom_data: dict#
Contents