# 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)

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*](https://docs.python.org/3/builtins/stdtypes.html#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*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any) *]* *,* [*BeforeValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.BeforeValidator) *(**func=~contextgem.internal.typings.validators._validate_is_json_dict* *,* *json_schema_input_type=PydanticUndefined* *)* *]*)
  * **mime_type** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'image/jpg'* *,*  *'image/jpeg'* *,*  *'image/png'* *,*  *'image/webp'* *]*)
  * **base64_data** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *,* [*StringConstraints*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.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:
: ```python
  from pathlib import Path
  <br/>
  from contextgem import Document, Image, create_image, image_to_base64
  <br/>
  <br/>
  # Path is adapted for doc tests
  current_file = Path(__file__).resolve()
  root_path = current_file.parents[4]
  <br/>
  # 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
  <br/>
  # Using pre-encoded base64 data directly
  png_image = Image(
      mime_type="image/png",
      base64_data="base64-string",  # image as a base64 string
  )
  <br/>
  # Using a different supported image format with create_image
  webp_image = create_image(root_path / "tests" / "images" / "invoices" / "invoice.webp")
  <br/>
  # 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))
  <br/>
  # Attaching an image to a document
  # Documents can contain both text and multiple images, or just images
  <br/>
  # 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],
  )
  <br/>
  # 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`](https://docs.python.org/3/library/typing.html#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`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any)]) – Dictionary containing the serialized object data.
* **Returns:**
  A new instance of the class with restored attributes.
* **Return type:**
  [`typing.Self`](https://docs.python.org/3/library/typing.html#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`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#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`](https://docs.python.org/3/library/typing.html#typing.Self)
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#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**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the serialized data is of another class.
  * [**OSError**](https://docs.python.org/3/builtins/exceptions.html#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`](https://docs.python.org/3/builtins/stdtypes.html#str)) – JSON string containing the serialized object data.
* **Returns:**
  A new instance of the class with restored state.
* **Return type:**
  [`typing.Self`](https://docs.python.org/3/library/typing.html#typing.Self)
* **Raises:**
  * [**json.JSONDecodeError**](https://docs.python.org/3/library/json.html#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**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the JSON value is not an object with a class name,
    i.e. not serialized data.
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#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`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`typing.Any`](https://docs.python.org/3/library/typing.html#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`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#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`](https://docs.python.org/3/builtins/constants.html#None)
* **Returns:**
  None
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the file path doesn’t end with ‘.json’.
  * [**OSError**](https://docs.python.org/3/builtins/exceptions.html#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`](https://docs.python.org/3/builtins/stdtypes.html#str)

#### *property* unique_id *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Returns the ULID of the instance.

#### mime_type *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['image/jpg', 'image/jpeg', 'image/png', 'image/webp']*

#### base64_data *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True), [StringConstraints](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.StringConstraints)(strip_whitespace=True, to_upper=[None](https://docs.python.org/3/builtins/constants.html#None), to_lower=[None](https://docs.python.org/3/builtins/constants.html#None), strict=[None](https://docs.python.org/3/builtins/constants.html#None), min_length=1, max_length=[None](https://docs.python.org/3/builtins/constants.html#None), pattern=[None](https://docs.python.org/3/builtins/constants.html#None), ascii_only=[None](https://docs.python.org/3/builtins/constants.html#None))]*

#### custom_data *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)], [BeforeValidator](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.BeforeValidator)(func=\_validate_is_json_dict, json_schema_input_type=PydanticUndefined)]*