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, ascii_only=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. Set modality="image" or modality="multimodal" on a concept to extract it from images, and use an LLM that supports vision.

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.

A deserialized model or model group has no API credentials, as they are not included in the serialized data, i.e. they are to be set again.

Parameters:

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

Returns:

A new instance of the class with restored attributes.

Return type:

typing.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 | pathlib.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:

typing.Self

Raises:

  • ValueError – If the file path doesn’t end with ‘.json’, or if the file does not hold valid serialized data, e.g. it is not a valid UTF-8 text (UnicodeDecodeError) or JSON (json.JSONDecodeError), or the data fails validation (pydantic’s ValidationError). These errors are subclasses of ValueError.

  • TypeError – If the serialized data is of another class.

  • OSError – If the file cannot be read, e.g. it does not exist. The error is the one raised by the file operation, e.g. FileNotFoundError or PermissionError.

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:

typing.Self

Raises:

  • json.JSONDecodeError – If the string is not a valid JSON. The error gives the position of what is invalid, and does not hold the string.

  • ValueError – If the JSON value is not an object with a class name, i.e. not serialized data.

  • 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 a model or model 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, typing.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 | pathlib.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’.

  • OSError – If the file cannot be written, e.g. its directory does not exist. The error is the one raised by the file operation, e.g. FileNotFoundError or PermissionError.

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: 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, ascii_only=None)]#
custom_data: Annotated[dict[str, Any], BeforeValidator(func=_validate_is_json_dict, json_schema_input_type=PydanticUndefined)]#