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.

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

Bases: _Image

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 (Annotated[dict[str, Any], BeforeValidator(func=~contextgem.internal.typings.validators._validate_is_json_dict, json_schema_input_type=PydanticUndefined)])

  • 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 document-level concept extraction is supported for images. Use LLM with role "extractor_vision", "reasoner_vision", "extractor_multimodal", or "reasoner_multimodal" 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.

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.

mime_type: Literal['image/jpg', 'image/jpeg', 'image/png', 'image/webp']#
base64_data: NonEmptyStr#
custom_data: JSONDictField#
Contents