# Concepts

Module for handling concepts at aspect and document levels.

This module provides classes for defining different types of concepts that can be
extracted from documents and aspects. Concepts represent specific pieces of information
to be identified and extracted by models, such as strings, numbers, boolean values,
JSON objects, and ratings.

Each concept type has specific properties and behaviors tailored to the kind of data
it represents, including validation rules, extraction methods, and reference handling.
Concepts can be attached to documents or aspects and can include examples, justifications,
and references to the source text.

### *class* contextgem.public.concepts.StringConcept(\*\*data)

Bases: `_StringConcept`

A concept model for string-based information extraction from documents and aspects.

This class provides functionality for defining, extracting, and managing string data
as conceptual entities within documents or aspects.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **examples** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*StringExample*](https://contextgem.shcherbak.ai/api/examples/index.html.md#contextgem.public.examples.StringExample) *]*) – Example strings illustrating the concept usage.
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** (*StrictBool*) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “document title” vs “key findings”).
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **examples** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[* *\_StringExample* *]*)

Example:
: ```python
  from contextgem import StringConcept, StringExample
  <br/>
  <br/>
  # Define a string concept for identifying contract party names
  # and their roles in the contract
  party_names_and_roles_concept = StringConcept(
      name="Party names and roles",
      description=(
          "Names of all parties entering into the agreement and their contractual roles"
      ),
      examples=[
          StringExample(
              content="X (Client)",  # guidance regarding format
          )
      ],
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]*

Provides access to extracted items.

* **Returns:**
  A list containing the extracted items as \_ExtractedItem objects.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]

#### *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.

#### examples *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_StringExample]*

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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

### *class* contextgem.public.concepts.BooleanConcept(\*\*data)

Bases: `_BooleanConcept`

A concept model for boolean (True/False) information extraction from documents and aspects.

This class handles identification and extraction of boolean values that represent
conceptual properties or attributes within content.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** (*StrictBool*) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “contains confidential information” vs “compliance violations”). A decision model
    (`DocumentDecisionModel`) extracts at most one item for a concept in any case,
    unless the text is sent in parts (`max_paragraphs_to_analyze_per_call` passed to
    the extraction method): it then returns an item for each part, and rejects a concept
    with `singular_occurrence=True` with `ValueError`.
  * **decision_threshold** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *|* *None*) – The lowest probability of “yes” (above 0, up to 1) with which
    a decision model (`DocumentDecisionModel`) sets the value of the concept to True.
    Defaults to None, in which case the `decision_threshold` of the decision model
    applies. Ignored when the concept is extracted by an LLM.
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **decision_threshold** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*float*](https://docs.python.org/3/builtins/functions.html#float) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*  *|* *None*)

Example:
: ```python
  from contextgem import BooleanConcept
  <br/>
  <br/>
  # Create the concept with specific configuration
  has_confidentiality = BooleanConcept(
      name="Contains confidentiality clause",
      description="Determines whether the contract includes provisions requiring parties to maintain confidentiality",
      model_role="reasoner",
      singular_occurrence=True,
      add_justifications=True,
      justification_depth="brief",
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]*

Provides access to extracted items.

* **Returns:**
  A list containing the extracted items as \_ExtractedItem objects.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]

#### *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.

#### decision_threshold *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[float](https://docs.python.org/3/builtins/functions.html#float), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)] | [None](https://docs.python.org/3/builtins/constants.html#None)*

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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

### *class* contextgem.public.concepts.NumericalConcept(\*\*data)

Bases: `_NumericalConcept`

A concept model for numerical information extraction from documents and aspects.

This class handles identification and extraction of numeric values (integers, floats,
or both) that represent conceptual measurements or quantities within content.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **numeric_type** (*Literal* *[* *"int"* *,*  *"float"* *,*  *"any"* *]*) – Type constraint for extracted numbers (“int”, “float”, or “any”).
    Defaults to “any” for auto-detection.
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** (*StrictBool*) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “total revenue” vs “monthly sales figures”).
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **numeric_type** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'int'* *,*  *'float'* *,*  *'any'* *]*)

Example:
: ```python
  from contextgem import NumericalConcept
  <br/>
  <br/>
  # Create concepts for different numerical values in the contract
  payment_amount = NumericalConcept(
      name="Payment amount",
      description="The monetary value to be paid according to the contract terms",
      numeric_type="float",
      add_references=True,
      reference_depth="sentences",
  )
  <br/>
  payment_days = NumericalConcept(
      name="Payment term days",
      description="The number of days within which payment must be made",
      numeric_type="int",
      add_justifications=True,
      justification_depth="balanced",
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]*

Provides access to extracted items.

* **Returns:**
  A list containing the extracted items as \_ExtractedItem objects.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]

#### *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.

#### numeric_type *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['int', 'float', 'any']*

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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

### *class* contextgem.public.concepts.RatingConcept(\*\*data)

Bases: `_RatingConcept`

A concept model for rating-based information extraction with defined scale boundaries.

This class handles identification and extraction of integer ratings that must fall within
the boundaries of a specified rating scale.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **rating_scale** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*int*](https://docs.python.org/3/builtins/functions.html#int) *]*) – The rating scale defining valid value boundaries, as a tuple of
    (start, end) integers.
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** (*StrictBool*) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “product rating score” vs “customer satisfaction ratings”). A decision model
    (`DocumentDecisionModel`) extracts at most one item for a concept in any case,
    unless the text is sent in parts (`max_paragraphs_to_analyze_per_call` passed to
    the extraction method): it then returns an item for each part, and rejects a concept
    with `singular_occurrence=True` with `ValueError`.
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **rating_scale** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple) *[*[*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]* *,* [*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]* *]*)

Example:
: ```python
  from contextgem import RatingConcept
  <br/>
  <br/>
  # Create a concept to rate the fairness of contract terms
  fairness_rating = RatingConcept(
      name="Contract fairness rating",
      description="Evaluation of how balanced and fair the contract terms are for all parties",
      rating_scale=(1, 5),
      model_role="reasoner",
      add_justifications=True,
      justification_depth="comprehensive",
      justification_max_sents=10,
  )
  <br/>
  # Create a concept to rate the clarity of contract language
  clarity_rating = RatingConcept(
      name="Language clarity rating",
      description="Assessment of how clear and unambiguous the contract language is",
      rating_scale=(1, 10),
      model_role="reasoner",
      add_justifications=True,
      justification_depth="balanced",
      justification_max_sents=3,
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_IntegerItem]*

Gets the list of extracted rating items.

* **Returns:**
  List of extracted integer items representing ratings.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_IntegerItem]

#### *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.

#### rating_scale *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)], [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]]*

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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

### *class* contextgem.public.concepts.JsonObjectConcept(\*\*data)

Bases: `_JsonObjectConcept`

A concept model for structured JSON object extraction from documents and aspects.

This class handles identification and extraction of structured data in JSON format,
with validation against a predefined schema structure.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **structure** ([*type*](https://docs.python.org/3/builtins/functions.html#type) *|* [*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *Any* *]*) – 

    JSON object schema as a class with type annotations or dictionary where keys
    are field names and values are type annotations. All dictionary keys must be strings.
    Supports generic aliases, union types, nested dictionaries for complex hierarchical structures,
    lists of dictionaries for array items, Literal types, and classes with type annotations
    (Pydantic models, dataclasses, etc.) for nested structures. All annotated types must be
    JSON-serializable, and mappings must have string keys (`dict[str, ...]`), as JSON
    objects do. Extracted values are validated strictly against the structure.
    Examples:
    - Simple structure: `{"item": str, "amount": int | float}`
    - Nested structure: `{"item": str, "details": {"price": float, "quantity": int}}`
    - List of objects: `{"items": [{"name": str, "price": float}]}`
    - List of primitives: `{"names": [str], "scores": [int | float], "statuses": [Literal["active", "inactive"]]}`
    - List of classes: `{"addresses": [AddressModel], "users": [UserModel]}`
    - Literal values: `{"status": Literal["pending", "completed", "failed"]}`
    - With type annotated classes: `{"address": AddressModel}` where AddressModel can be a
      Pydantic model, dataclass, or any class with type annotations

    **Note**: For lists, you can use either generic syntax (`list[str]`) or literal syntax
    (`[str]`). List instances support primitive types, unions, literals, and typed classes.
    Both `{"items": [ClassName]}` and `{"items": list[ClassName]}` are equivalent.

    **Note**: Class types cannot be used as dictionary keys or values. For example,
    `dict[str, Address]` is not allowed. Use alternative structures like nested objects
    or lists of objects instead.

    **Note**: When using classes that contain other classes as type hints, inherit from
    `JsonObjectClassStruct` in all parts of the class hierarchy, to ensure proper conversion
    of nested class hierarchies to dictionary representations for serialization.

    **Tip**: do not overcomplicate the structure to avoid prompt overloading.
  * **examples** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*JsonObjectExample*](https://contextgem.shcherbak.ai/api/examples/index.html.md#contextgem.public.examples.JsonObjectExample) *]*) – Example JSON objects illustrating the concept usage.
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** (*StrictBool*) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “product specifications” vs “customer order details”).
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **structure** ([*type*](https://docs.python.org/3/builtins/functions.html#type) *|* [*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*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* *)* *]* *,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any) *]*)
  * **examples** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[* *\_JsonObjectExample* *]*)

Example:
: ```python
  from typing import Literal
  <br/>
  from contextgem import JsonObjectConcept
  <br/>
  <br/>
  # Define a JSON object concept for capturing address information
  address_info_concept = JsonObjectConcept(
      name="Address information",
      description=(
          "Structured address data from text including street, "
          "city, state, postal code, and country."
      ),
      structure={
          "street": str | None,
          "city": str | None,
          "state": str | None,
          "postal_code": str | None,
          "country": str | None,
          "address_type": Literal["residential", "business"] | None,
      },
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]*

Provides access to extracted items.

* **Returns:**
  A list containing the extracted items as \_ExtractedItem objects.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]

#### *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.

#### structure *: [type](https://docs.python.org/3/builtins/functions.html#type) | [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[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))], [Any](https://docs.python.org/3/library/typing.html#typing.Any)]*

#### examples *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_JsonObjectExample]*

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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

### *class* contextgem.public.concepts.DateConcept(\*\*data)

Bases: `_DateConcept`

A concept model for date object extraction from documents and aspects.

This class handles identification and extraction of dates, with support for parsing
string representations in a specified format into Python date objects.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** (*StrictBool*) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “contract signing date” vs “meeting dates”).
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)

Example:
: ```python
  from contextgem import DateConcept
  <br/>
  <br/>
  # Create a date concept to extract the effective date of the contract
  effective_date = DateConcept(
      name="Effective date",
      description="The effective date as specified in the contract",
      add_references=True,  # Include references to where dates were found
      singular_occurrence=True,  # Only extract one effective date per document
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]*

Provides access to extracted items.

* **Returns:**
  A list containing the extracted items as \_ExtractedItem objects.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_ExtractedItem]

#### *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.

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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

### *class* contextgem.public.concepts.LabelConcept(\*\*data)

Bases: `_LabelConcept`

A concept model for label-based classification of documents and aspects.

This class handles identification and classification using predefined labels,
supporting both multi-class (single label selection) and multi-label (multiple
label selection) classification approaches.

**Note**: Behavior depends on `classification_type`:

- `multi_class`: exactly one label is always returned for each extracted item. If
  none of the specific labels apply, include a catch-all label (e.g., `"other"`,
  `"N/A"`) among `labels` so the model can select it.
- `multi_label`: when none of the predefined labels apply, no extracted items may
  be returned (empty `extracted_items` list). This prevents forced classification
  when no appropriate label exists.

* **Variables:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the concept (non-empty string, stripped).
  * **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – A brief description of the concept (non-empty string, stripped).
  * **labels** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *]*) – List of predefined labels (non-empty strings, stripped) for classification.
    Must contain at least 2 unique labels.
  * **classification_type** (*ClassificationType*) – Classification mode - “multi_class” for single label selection,
    “multi_label” for multiple label selection. Defaults to “multi_class”.
  * **model_role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – The role label of the model that extracts the concept when
    a `DocumentModelGroup` is used: the concept is routed to the model in the group
    with the same `role`. Defaults to None, which routes the concept to the model
    without a role. Ignored by a standalone model, which extracts every
    concept it is given.
  * **modality** (*Modality*) – The document content the concept is extracted from: “text”, “image”,
    or “multimodal” (text and/or images, whichever the document has). “image” and
    “multimodal” are supported for document-level concepts only. Defaults to “text”.
  * **add_justifications** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include justifications for extracted items.
  * **justification_depth** (*JustificationDepth*) – Justification detail level. Defaults to “brief”.
  * **justification_max_sents** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Maximum sentences in justification. Defaults to 2.
  * **add_references** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to include source references for extracted items.
  * **reference_depth** (*ReferenceDepth*) – Source reference granularity (“paragraphs” or “sentences”).
    Defaults to “paragraphs”. Only relevant when references are added to extracted items.
    Affects the structure of `extracted_items`.
  * **singular_occurrence** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether this concept has at most one extracted item. If True,
    at most one item is extracted, and none if there is nothing to extract: an LLM that
    returns more than one is asked again, as for any other invalid data. Defaults to
    False (multiple extracted items are allowed). Note that with advanced LLMs, this
    constraint may not be strictly required as they can often infer the appropriate
    number of items to extract from the concept’s name, description, and type (e.g.,
    “document type” vs “content topics”). A decision model (`DocumentDecisionModel`)
    extracts at most one item for a concept in any case, unless the text is sent in
    parts (`max_paragraphs_to_analyze_per_call` passed to the extraction method): it
    then returns an item for each part, and rejects a concept with
    `singular_occurrence=True` with `ValueError`.
  * **decision_threshold** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *|* *None*) – The lowest probability (above 0, up to 1) with which
    a decision model (`DocumentDecisionModel`) selects a label of the concept.
    Can be set for the “multi_label” classification type only: with “multi_class”,
    the most probable label is always selected. Defaults to None, in which case
    the `decision_threshold` of the decision model applies. Ignored when
    the concept is extracted by an LLM.
* **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* *)* *]*)
  * **add_justifications** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **justification_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'brief'* *,*  *'balanced'* *,*  *'comprehensive'* *]*)
  * **justification_max_sents** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **name** ([*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* *)* *]*)
  * **description** ([*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* *)* *]*)
  * **model_role** ([*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* *)* *,* [*AfterValidator*](https://pydantic.dev/docs/validation/latest/api/pydantic/functional_validators/#pydantic.functional_validators.AfterValidator) *(**func=~contextgem.internal.typings.validators._validate_model_role* *)* *]*  *|* *None*)
  * **modality** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'text'* *,*  *'image'* *,*  *'multimodal'* *]*)
  * **add_references** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **reference_depth** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'paragraphs'* *,*  *'sentences'* *]*)
  * **singular_occurrence** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*)
  * **labels** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*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* *)* *]* *]*)
  * **classification_type** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal) *[* *'multi_class'* *,*  *'multi_label'* *]*)
  * **decision_threshold** ([*Annotated*](https://docs.python.org/3/library/typing.html#typing.Annotated) *[*[*float*](https://docs.python.org/3/builtins/functions.html#float) *,* [*Strict*](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict) *(**strict=True* *)* *]*  *|* *None*)

Example:
: ```python
  from contextgem import LabelConcept
  <br/>
  <br/>
  # Multi-class classification: single label selection
  document_type_concept = LabelConcept(
      name="Document Type",
      description="Classify the type of legal document",
      labels=["NDA", "Consultancy Agreement", "Privacy Policy", "Other"],
      classification_type="multi_class",
      singular_occurrence=True,
  )
  <br/>
  # Multi-label classification: multiple label selection
  content_topics_concept = LabelConcept(
      name="Content Topics",
      description="Identify all relevant topics covered in the document",
      labels=["Finance", "Legal", "Technology", "HR", "Operations", "Marketing"],
      classification_type="multi_label",
      add_justifications=True,  # add justifications for the selected labels
      justification_depth="brief",
  )
  ```

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.

#### *property* extracted_items *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_LabelItem]*

Gets the list of extracted label items.

* **Returns:**
  List of extracted label items.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[\_LabelItem]

#### *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.

#### labels *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[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))]]*

#### classification_type *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['multi_class', 'multi_label']*

#### decision_threshold *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[float](https://docs.python.org/3/builtins/functions.html#float), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)] | [None](https://docs.python.org/3/builtins/constants.html#None)*

#### name *: [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))]*

#### description *: [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))]*

#### modality *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['text', 'image', 'multimodal']*

#### add_references *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### reference_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['paragraphs', 'sentences']*

#### singular_occurrence *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### add_justifications *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[bool](https://docs.python.org/3/builtins/functions.html#bool), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

#### justification_depth *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['brief', 'balanced', 'comprehensive']*

#### justification_max_sents *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[int](https://docs.python.org/3/builtins/functions.html#int), [Strict](https://pydantic.dev/docs/validation/latest/api/pydantic/types/#pydantic.types.Strict)(strict=True)]*

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