# Decision models

Module for handling processing logic using decision models.

This module provides the class for using a decision model in document processing
workflows. A decision model takes a text and a set of closed questions (yes/no, pick
one option, rate on a scale) and returns the probabilities of the answers. It generates
no text. It is used for what can be put as such questions: which paragraphs or
sentences of a document belong to an aspect, and the concepts whose values come from
a closed set of options. The probabilities are the model’s own estimate of each answer.

The requests are sent through the litellm library, which supports several providers
of decision models. The module covers the configuration of a model, the requests to
its API, and the tracking of token usage and costs.

### *class* contextgem.public.decision_models.DocumentDecisionModel(\*\*data)

Bases: `_DocumentDecisionModel`

Handles processing documents with a specific decision model.

A decision model answers closed questions on a text with probabilities and
generates no text. It extracts aspects, by deciding on each paragraph whether
the paragraph belongs to an aspect and, for an aspect with
`reference_depth="sentences"`, on each sentence of such a paragraph whether
the sentence does, and the concepts whose values come from
a closed set of options: `BooleanConcept`, `LabelConcept` and
`RatingConcept`. Each extracted item has the probabilities of all the options
in its `probabilities` attribute. A decision model can be used on its own or,
with a role assigned, as a part of a model group, next to the LLMs that extract
everything else.

* **Variables:**
  * **model** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Model identifier in format {model_provider}/{model_name}, e.g.
    `"typesafe/jev-latest"`. The model has to be served by one of the providers
    of decision models that `litellm` supports: a model of another provider
    is rejected when the decision model is created. For a model deployed in
    Microsoft Foundry, the name of the deployment takes the place of the model
    name, i.e. `"azure_ai/<deployment_name>"`.
  * **api_key** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – API key for authentication. Not required for self-hosted models.
    Not included in the serialized model data, i.e. to be set again after
    deserialization. Not shown when the model is printed, nor in the text of
    a validation error of the model, which names the invalid parameter and
    the reason without showing the values passed. The values are still returned
    by the `errors()` and `json()` methods of the error, unless
    `include_input=False` is passed, with `'**********'` in place of a key
    that is passed as a value, e.g. a rejected key or the key among
    the parameters that a model is created with, and in place of the value of
    any parameter that a model does not have, as it may be the key passed under
    a misspelled name. A model that is among the values is returned by
    `errors()` as it is, i.e. with the key as its attribute, and is written
    out by `json()` without its key. A key that is passed as the value of
    another parameter, e.g. of `model`, is returned as any other value.
  * **api_base** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – Base URL of the API endpoint, e.g. the address of a self-hosted
    server, or the endpoint of the Microsoft Foundry resource that the model is
    deployed in. Not included in the serialized model data, i.e. to be set
    again after deserialization.
  * **role** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – Free-form role label of the model (up to 64 printable characters), used
    for routing in a `DocumentModelGroup`: the model extracts the aspects/concepts
    with the same `model_role`. Defaults to None, in which case the model extracts
    the aspects/concepts without `model_role`. Ignored when the model is used on
    its own, as it then extracts all the aspects/concepts it is given.
  * **num_retries_failed_request** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Number of retries when a request fails with
    a transient error (request timeout, rate limit, server or connection error).
    Retries are performed with exponential backoff and jitter. Non-transient errors
    (e.g. invalid request, failed authentication) are not retried. Defaults to 3.
  * **timeout** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – Timeout in seconds for API calls. Defaults to 600 seconds.
  * **pricing_details** ([*ModelPricing*](https://contextgem.shcherbak.ai/api/data_models/index.html.md#contextgem.public.data_models.ModelPricing) *|* *None*) – ModelPricing object with pricing details for cost calculation.
    Decision models are usually priced by the input tokens only, in which case
    the price of the output tokens is to be set to `0.0`. Defaults to None.
  * **auto_pricing** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Enable automatic cost calculation using genai-prices. Cannot be
    set together with `pricing_details`. For an OpenAI model (`openai/`),
    the prices of the decision requests are used, which genai-prices has apart
    from the prices of the chat requests to the model. Not supported for
    a model for which genai-prices has the prices of a text-generating model,
    i.e. a price of output tokens, which are the prices of the chat requests
    to the model (e.g. `openrouter/openai/gpt-6-luna`), and for self-hosted
    models (`strands_decider/`): set `pricing_details` for them instead.
    For a model that genai-prices has no prices for, e.g. a model deployed in
    Microsoft Foundry, a warning is issued and the costs stay at zero:
    `pricing_details` is to be set instead for such a model too. Defaults to
    `False`.
  * **auto_pricing_refresh** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether genai-prices should auto-refresh its cached
    pricing data, e.g. to price a recently released model that the bundled
    pricing data does not include yet. Defaults to `False`.
  * **is_fallback** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Indicates whether the model is a fallback model. Defaults to False.
  * **fallback_models** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*DocumentDecisionModel*](#contextgem.public.decision_models.DocumentDecisionModel) *|* [*DocumentLLM*](https://contextgem.shcherbak.ai/api/llms/index.html.md#contextgem.public.llms.DocumentLLM) *]*) – Models to use as fallbacks if the current one fails, tried
    in the given order until one of them succeeds: decision models, LLMs, or both.
    Each must have `is_fallback=True` and the same role as the current model, and
    must differ from the current model and from each other in at least one config
    param. A fallback LLM extracts the same aspects/concepts with its prompts,
    i.e. its items have no probabilities, and is asked again when it returns
    invalid data, up to its `max_retries_invalid_data` times, while a fallback
    decision model is asked once. Defaults to an empty list.
  * **decision_threshold** ([*float*](https://docs.python.org/3/builtins/functions.html#float)) – The lowest probability of “yes” (above 0, up to 1) with
    which a yes/no question is taken as answered “yes”: a paragraph or a sentence
    belongs to an aspect, a `BooleanConcept` is `True`, a label of
    a `LabelConcept` with
    `classification_type="multi_label"` is selected. A lower threshold extracts
    more, a higher one extracts only what the model is surer of. Applies unless
    the aspect or the concept has a `decision_threshold` of its own. Does not
    apply to a `LabelConcept` with `classification_type="multi_class"` and to
    a `RatingConcept`, for which the most probable option is taken. Does not
    change the `probabilities` of the extracted items. Defaults to 0.5.
  * **async_limiter** (*AsyncLimiter*) – Controls frequency of async API requests for concurrent tasks.
    Defaults to allowing 10 acquisitions per 10-second period to prevent rate limit issues.
    With concurrency enabled, the requests for the paragraphs of a document, which
    aspects are extracted with, are paced by the limiter: consider a higher rate
    for long documents, if the rate limits of the model provider allow for it.
    The rate applies to all the requests to the model that are sent concurrently,
    i.e. the extraction calls that run at the same time share it.
    Requests to a fallback model are controlled by the limiter of that fallback model.
    See [https://github.com/mjpieters/aiolimiter](https://github.com/mjpieters/aiolimiter) for configuration details.
* **Parameters:**
  * **model** ([*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* *)* *]*)
  * **api_key** ([*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* *)* *]*  *|* *None*)
  * **api_base** ([*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* *)* *]*  *|* *None*)
  * **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*)
  * **num_retries_failed_request** ([*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* *)* *]*)
  * **timeout** ([*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* *)* *]*)
  * **pricing_details** ( *\_ModelPricing* *|* *None*)
  * **is_fallback** ([*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* *)* *]*)
  * **fallback_models** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[* *\_DocumentModel* *]*)
  * **auto_pricing** ([*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* *)* *]*)
  * **auto_pricing_refresh** ([*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* *)* *]*)

Note:
: For what a decision model extracts, how its requests are formed, how
  the extracted items get their values and probabilities, and the limits,
  see [https://contextgem.shcherbak.ai/decision_models/decision_models/](https://contextgem.shcherbak.ai/decision_models/decision_models/)

Example:
: ```python
  from contextgem import (
      DocumentDecisionModel,
      DocumentLLM,
      DocumentModelGroup,
  )
  <br/>
  <br/>
  # Create a decision model. A decision model answers closed questions on a text
  # with probabilities: it extracts aspects, and Boolean, label and rating concepts.
  decision_model = DocumentDecisionModel(
      model="typesafe/jev-latest",
      api_key="your-typesafe-api-key",  # Replace with your actual API key
      role="decide",  # A label of your choice, needed for routing in a model group
      auto_pricing=True,  # optional, to calculate the costs with `genai-prices`
  )
  <br/>
  # Create a fallback LLM in case the decision model fails. It extracts
  # the same aspects and concepts with its prompts, i.e. without the probabilities.
  decision_model_fallback = DocumentLLM(
      model="openai/gpt-6-luna",
      api_key="your-openai-api-key",  # Replace with your actual API key
      role="decide",  # Must have the same role as the model it is a fallback for
      is_fallback=True,
  )
  decision_model.fallback_models = [decision_model_fallback]
  <br/>
  # Create an LLM for everything else. This LLM has no role, i.e. it extracts
  # the aspects and concepts that have no `model_role`.
  llm = DocumentLLM(
      model="openai/gpt-6-luna",
      api_key="your-openai-api-key",  # Replace with your actual API key
  )
  <br/>
  # Create a DocumentModelGroup. The aspects and concepts with `model_role="decide"`
  # are extracted by the decision model, and all the other ones by the LLM.
  model_group = DocumentModelGroup(models=[llm, decision_model])
  ```

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.

#### \_eq_deserialized_model_config(other)

Custom config equality method to compare this model with a deserialized instance.

Compares the \_\_dict_\_ of both instances and performs specific checks for
certain attributes that require special handling: first for what models
of all kinds have, then for what only the specific kind of the model has
(see `_eq_deserialized_kind_specific_config`).

Note that, by default, the reconstructed deserialized model will be only partially
equal (==) to the original one, as the api credentials are redacted, and the async
limiter and the async lock are not serialized and point to different objects
in memory post-initialization. Also, usage and cost are reset by default pre-serialization.

* **Parameters:**
  **other** (`contextgem.internal.base.models._DocumentModel`) – Another model instance to compare with
* **Returns:**
  True if the instances are equal, False otherwise
* **Return type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* async_limiter *: AsyncLimiter*

Gets the async rate limiter for this model.

* **Returns:**
  The AsyncLimiter instance controlling request rate limits.
* **Return type:**
  AsyncLimiter

#### extract_all(document, \*, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, max_images_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Extracts all aspects and concepts from a document and its aspects.

This method performs comprehensive extraction by processing the document for aspects
and concepts, then extracting concepts from each aspect. The operation can be
configured for concurrent processing and customized extraction parameters.

This is the synchronous version of extract_all_async().

* **Parameters:**
  * **document** (`contextgem.internal.base.documents._Document`) – The document to analyze.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed aspects and concepts with
    newly extracted information. Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of items with the same extraction params to process
    in each call. Defaults to 0 (all items in one call). If concurrency is enabled, defaults to 1.
    For complex tasks, you should not set a high value, in order to avoid prompt overloading.
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to include in a
    single LLM prompt. A decision model is sent each paragraph in a request of
    its own for aspects, whatever the value. For concepts, it is sent a text
    with more paragraphs in parts of at most that many paragraphs, each in
    a request of its own: a concept then gets an extracted item for each part,
    and a concept with `singular_occurrence=True` is rejected with
    `ValueError`. Defaults to 0 (all paragraphs). Cannot be negative.
  * **max_images_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum images to include in a single LLM prompt.
    Defaults to 0 (all images). Cannot be negative. Relevant only for document-level
    concepts.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  The document with extracted aspects and concepts.
* **Return type:**
  `contextgem.internal.base.documents._Document`

#### *async* extract_all_async(document, \*, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, max_images_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Asynchronously extracts all aspects and concepts from a document and its aspects.

This method performs comprehensive extraction by processing the document for aspects
and concepts, then extracting concepts from each aspect. The operation can be
configured for concurrent processing and customized extraction parameters.

* **Parameters:**
  * **document** (`contextgem.internal.base.documents._Document`) – The document to analyze.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed aspects and concepts with
    newly extracted information. Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of items with the same extraction params to process
    in each call. Defaults to 0 (all items in one call). If concurrency is enabled,
    defaults to 1. For complex tasks, you should not set a high value, in order to avoid
    prompt overloading.
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to include in a
    single LLM prompt. A decision model is sent each paragraph in a request of
    its own for aspects, whatever the value. For concepts, it is sent a text
    with more paragraphs in parts of at most that many paragraphs, each in
    a request of its own: a concept then gets an extracted item for each part,
    and a concept with `singular_occurrence=True` is rejected with
    `ValueError`. Defaults to 0 (all paragraphs). Cannot be negative.
  * **max_images_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum images to include in a single LLM prompt.
    Defaults to 0 (all images). Cannot be negative. Relevant only for document-level
    concepts.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  The document with extracted aspects and concepts.
* **Return type:**
  `contextgem.internal.base.documents._Document`

#### extract_aspects_from_document(document, \*, from_aspects=None, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Extracts aspects from the provided document using predefined models.

If an aspect instance has `extracted_items` populated, the `reference_paragraphs` field will be
automatically populated from these items. For an aspect with the “sentences” reference depth,
the `reference_sentences` field is populated from them as well: with the extracted sentences,
and not with the other sentences of the reference paragraphs.

This is the synchronous version of extract_aspects_from_document_async().

* **Parameters:**
  * **document** (`contextgem.internal.base.documents._Document`) – The document from which aspects are to be extracted.
  * **from_aspects** ([`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[`contextgem.internal.base.aspects._Aspect`] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Existing aspects to use as a base for extraction. If None, uses all
    document’s aspects. An aspect that is given more than once is extracted once.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed aspects with newly extracted information.
    Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum items with the same extraction params to process per call.
    Defaults to 0 (all items in single call). For complex tasks, you should not set a value, to avoid
    prompt overloading. If concurrency is enabled, defaults to 1 (each item processed separately).
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to analyze in a single LLM
    prompt. Changes nothing for a decision model, which is sent each paragraph in
    a request of its own. Defaults to 0 (all paragraphs). Cannot be negative.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  List of processed \_Aspect objects with extracted items.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.base.aspects._Aspect`]

#### *async* extract_aspects_from_document_async(document, \*, from_aspects=None, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Extracts aspects from the provided document using predefined models asynchronously.

If an aspect instance has `extracted_items` populated, the `reference_paragraphs` field will be
automatically populated from these items. For an aspect with the “sentences” reference depth,
the `reference_sentences` field is populated from them as well: with the extracted sentences,
and not with the other sentences of the reference paragraphs.

* **Parameters:**
  * **document** (`contextgem.internal.base.documents._Document`) – The document from which aspects are to be extracted.
  * **from_aspects** ([`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[`contextgem.internal.base.aspects._Aspect`] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Existing aspects to use as a base for extraction. If None, uses all
    document’s aspects. An aspect that is given more than once is extracted once.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed aspects with newly extracted information.
    Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of items with the same extraction params to process
    per call. Defaults to 0 (all items in one call). If concurrency is enabled,
    defaults to 1. For complex tasks, you should not set a high value, in order to avoid
    prompt overloading.
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to analyze in a single LLM
    prompt. Changes nothing for a decision model, which is sent each paragraph in
    a request of its own. Defaults to 0 (all paragraphs). Cannot be negative.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  List of processed \_Aspect objects with extracted items.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.base.aspects._Aspect`]

#### extract_concepts_from_aspect(aspect, document, \*, from_concepts=None, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Extracts concepts associated with a given aspect in a document.

This method processes an aspect to extract related concepts using models.
If the aspect has not been previously processed, a ValueError is raised.

This is the synchronous version of extract_concepts_from_aspect_async().

* **Parameters:**
  * **aspect** (`contextgem.internal.base.aspects._Aspect`) – The aspect from which to extract concepts.
  * **document** (`contextgem.internal.base.documents._Document`) – The document that contains the aspect.
  * **from_concepts** ([`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[`contextgem.internal.base.concepts._Concept`] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – List of existing concepts to process. Defaults to None.
    A concept that is given more than once is extracted once.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed concepts with newly
    extracted information. Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of items with the same extraction params to process
    in each call. Defaults to 0 (all items in one call). If concurrency is enabled,
    defaults to 1. For complex tasks, you should not set a high value, in order to avoid
    prompt overloading.
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to include in a
    single LLM prompt. A decision model is sent a text with more
    paragraphs in parts of at most that many paragraphs, each in a request of
    its own: a concept then gets an extracted item for each part, and
    a concept with `singular_occurrence=True` is rejected with `ValueError`.
    Defaults to 0 (all paragraphs). Cannot be negative.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  List of processed concept objects.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.base.concepts._Concept`]

#### *async* extract_concepts_from_aspect_async(aspect, document, \*, from_concepts=None, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Asynchronously extracts concepts from a specified aspect using models.

This method processes an aspect to extract related concepts using models.
If the aspect has not been previously processed, a ValueError is raised.

* **Parameters:**
  * **aspect** (`contextgem.internal.base.aspects._Aspect`) – The aspect from which to extract concepts.
  * **document** (`contextgem.internal.base.documents._Document`) – The document that contains the aspect.
  * **from_concepts** ([`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[`contextgem.internal.base.concepts._Concept`] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – List of existing concepts to process. Defaults to None.
    A concept that is given more than once is extracted once.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed concepts with newly
    extracted information. Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of items with the same extraction params to process
    in each call. Defaults to 0 (all items in one call). If concurrency is enabled,
    defaults to 1. For complex tasks, you should not set a high value, in order to avoid
    prompt overloading.
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to include in a
    single LLM prompt. A decision model is sent a text with more
    paragraphs in parts of at most that many paragraphs, each in a request of
    its own: a concept then gets an extracted item for each part, and
    a concept with `singular_occurrence=True` is rejected with `ValueError`.
    Defaults to 0 (all paragraphs). Cannot be negative.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  List of processed concept objects.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.base.concepts._Concept`]

#### extract_concepts_from_document(document, \*, from_concepts=None, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, max_images_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Extracts concepts from the provided document using predefined models.

This is the synchronous version of extract_concepts_from_document_async().

* **Parameters:**
  * **document** (`contextgem.internal.base.documents._Document`) – The document from which concepts are to be extracted.
  * **from_concepts** ([`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[`contextgem.internal.base.concepts._Concept`] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Existing concepts to use as a base for extraction. If None, uses all
    document’s concepts. A concept that is given more than once is extracted once.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed concepts with
    newly extracted information. Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum items with the same extraction params to process per call.
    Defaults to 0 (all items in single call). For complex tasks, you should not set a value, to avoid
    prompt overloading. If concurrency is enabled, defaults to 1 (each item processed separately).
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to analyze in a single LLM
    prompt. A decision model is sent a text with more
    paragraphs in parts of at most that many paragraphs, each in a request of
    its own: a concept then gets an extracted item for each part, and
    a concept with `singular_occurrence=True` is rejected with `ValueError`.
    Defaults to 0 (all paragraphs). Cannot be negative.
  * **max_images_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum images to include in a single LLM prompt.
    Defaults to 0 (all images). Cannot be negative.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  List of processed Concept objects with extracted items.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.base.concepts._Concept`]

#### *async* extract_concepts_from_document_async(document, \*, from_concepts=None, overwrite_existing=False, max_items_per_call=0, use_concurrency=False, max_paragraphs_to_analyze_per_call=0, max_images_to_analyze_per_call=0, raise_exception_on_extraction_error=True)

Extracts concepts from the provided document using predefined models asynchronously.

This method processes a document to extract concepts using configured models.

* **Parameters:**
  * **document** (`contextgem.internal.base.documents._Document`) – The document from which concepts are to be extracted.
  * **from_concepts** ([`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[`contextgem.internal.base.concepts._Concept`] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Existing concepts to use as a base for extraction. If None, uses all
    document’s concepts. A concept that is given more than once is extracted once.
  * **overwrite_existing** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to overwrite already processed concepts with
    newly extracted information. Defaults to False.
  * **max_items_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of items with the same extraction params to process
    per call. Defaults to 0 (all items in one call). If concurrency is enabled,
    defaults to 1. For complex tasks, you should not set a high value, in order to avoid
    prompt overloading.
  * **use_concurrency** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, enables concurrent processing of multiple items.
    Concurrency can considerably reduce processing time, but may cause rate limit errors
    with model providers. Use this option when API rate limits allow for multiple concurrent
    requests. Defaults to False.
  * **max_paragraphs_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum paragraphs to analyze in a single LLM
    prompt. A decision model is sent a text with more
    paragraphs in parts of at most that many paragraphs, each in a request of
    its own: a concept then gets an extracted item for each part, and
    a concept with `singular_occurrence=True` is rejected with `ValueError`.
    Defaults to 0 (all paragraphs). Cannot be negative.
  * **max_images_to_analyze_per_call** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum images to include in a single LLM prompt.
    Defaults to 0 (all images). Cannot be negative.
  * **raise_exception_on_extraction_error** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to raise an exception if the extraction fails
    due to invalid data returned by a model or an error in the model API. If False, a warning will
    be issued instead, and no extracted items will be returned. Defaults to True.
* **Returns:**
  List of processed Concept objects with extracted items.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.base.concepts._Concept`]

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

#### get_cost()

Retrieves the accumulated cost information of the model and of its fallback
models, if configured.

This method collects cost statistics for the current model instance and for its
fallback models (if configured), providing insights into API usage expenses.

* **Returns:**
  A list of cost statistics containers for the model and its
  fallback models.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.data_models._ModelCostOutputContainer`]

#### get_usage()

Retrieves the usage information of the model and of its fallback models,
if configured.

This method collects token usage statistics for the current model instance and
for its fallback models (if configured), providing insights into API consumption.

* **Returns:**
  A list of usage statistics containers for the model and its
  fallback models.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`contextgem.internal.data_models._ModelUsageOutputContainer`]

#### *property* is_group *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Returns False indicating this is a single model, not a group.

* **Returns:**
  Always False for single models.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* list_roles *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)]*

Returns a list containing the role of this model.

(For a single model, this returns a list with just one element - the model’s role,
or None if the model has no role. For model groups, the method implementation returns
roles of all models in the group.)

* **Returns:**
  A list containing the role of this model.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str) | None]

#### reset_usage_and_cost()

Resets the usage and cost statistics for the model and its fallback models
(if configured).

This method clears accumulated usage and cost data, which is useful when processing
multiple documents sequentially and tracking metrics for each document separately.

* **Returns:**
  None
* **Return type:**
  [`None`](https://docs.python.org/3/builtins/constants.html#None)

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

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

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

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

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

#### 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=\_validate_model_role)] | [None](https://docs.python.org/3/builtins/constants.html#None)*

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

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

#### pricing_details *: \_ModelPricing | [None](https://docs.python.org/3/builtins/constants.html#None)*

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

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

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

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