Sentences

Sentences#

Module for handling document sentences.

This module provides the Sentence class, which represents a structured unit of text within a document paragraph. Sentences are the fundamental building blocks of text analysis, containing the raw text content of individual statements.

The module supports validation to ensure data integrity and integrates with the paragraph structure to maintain the hierarchical organization of document content.

class contextgem.public.sentences.Sentence(**data)[source]#

Bases: _Sentence

Represents a sentence within a document paragraph.

Sentences are immutable text units that serve as the fundamental building blocks for document analysis. The raw text content is preserved and cannot be modified after initialization to maintain data integrity.

Variables:

  • raw_text (str) – The complete text content of the sentence. This value is frozen after initialization.

  • additional_context (str | None) – Optional supplementary information about the sentence, as a single-line string. It is passed to the LLM together with the sentence text in the prompts that list sentences, i.e. when sentence-level references are used (reference_depth="sentences"). A decision model is sent it together with the sentence text when aspects are extracted with sentences as their items. Sentences that are segmented automatically inherit the additional context of their paragraph. Defaults to None.

Parameters:

  • custom_data (Annotated[dict[str, Any], BeforeValidator(func=~contextgem.internal.typings.validators._validate_is_json_dict, json_schema_input_type=PydanticUndefined)])

  • additional_context (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)] | None)

  • raw_text (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:

Normally, you do not need to construct sentences manually, as they are populated automatically from document’s raw_text or paragraphs attributes. Only use this constructor for advanced use cases, such as when you have a custom paragraph/sentence segmentation tool.

Example:
Sentence definition#
from contextgem import Sentence


# Create a sentence with raw text content
sentence = Sentence(raw_text="This is a simple sentence.")

# Sentences are immutable - their content cannot be changed after creation
try:
    sentence.raw_text = "Attempting to modify the sentence."
except ValueError as e:
    print(f"Error when trying to modify sentence: {e}")

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.

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