Exceptions and Warnings

Module exposing the exceptions that the framework raises to the calling code, and the category of the warnings that it issues.

The exceptions are the classes that the framework itself raises, so they can be used in except clauses: from contextgem import ModelAPIError, or ContextGemError, their base class, to catch any of them. Likewise, the warning category is the one of the warnings that the framework issues, so it can be used in warning filters: from contextgem import ContextGemWarning.

exception contextgem.public.exceptions.ContextGemError(message, retry_count=None, original_error=None)

Bases: Exception

Base class of the exceptions that the framework raises when a run fails, i.e. of ModelAPIError, ModelExtractionError and LLMToolLoopLimitError. Catch it to handle any of them in one clause, e.g. except ContextGemError.

An error in the calling code, e.g. an invalid argument or an object that cannot be used where it is passed, is raised as ValueError or TypeError instead, which includes the ValidationError of pydantic, a subclass of ValueError. A file that cannot be read or written, e.g. by from_disk() or to_disk(), raises OSError.

Can be imported from contextgem.

Variables:

• message (str) – Human-readable error description

• retry_count (int or None) – Number of retries attempted before failure

• original_error (Exception or None) – The underlying exception that caused the failure

Parameters:

• message (str)

• retry_count (int | None)

• original_error (Exception | None)

Initialize the exception.

Parameters:

• message (str) – Human-readable error description

• retry_count (int | None) – Number of retries attempted before failure

• original_error (Exception | None) – The underlying exception that caused the failure

exception contextgem.public.exceptions.ModelAPIError(message, retry_count=None, original_error=None)

Bases: ContextGemError

Exception raised when a request to a model fails for good, and there is no fallback model left to try.

This is the case when:

• the request fails with a non-transient error, e.g. an invalid request or a failed authentication;

• the request fails with a transient error (request timeout, rate limit, server or connection error), also after num_retries_failed_request retries;

• the response of an LLM is cut off at the max output tokens during extraction, or is empty in a chat.

During extraction, if raise_exception_on_extraction_error=False is passed to the extraction method, a warning is logged instead.

Can be imported from contextgem.

Variables:

• message (str) – Human-readable error description

• retry_count (int or None) – Number of retries attempted for the failed request

• original_error (Exception or None) – The underlying exception that caused the failure

Parameters:

• message (str)

• retry_count (int | None)

• original_error (Exception | None)

Initialize the exception.

Parameters:

• message (str) – Human-readable error description

• retry_count (int | None) – Number of retries attempted before failure

• original_error (Exception | None) – The underlying exception that caused the failure

exception contextgem.public.exceptions.ModelExtractionError(message, retry_count=None, original_error=None)

Bases: ContextGemError

Exception raised by the extraction methods when a model returns data that cannot be used, and there is no fallback model left to try.

This is the case when:

• the response of an LLM cannot be parsed or validated, also after the LLM was asked again max_retries_invalid_data times;

• the response of a decision model cannot be used, e.g. the model refused to answer a question of a concept. A decision model is not asked again.

If raise_exception_on_extraction_error=False is passed to the extraction method, a warning is logged instead.

Can be imported from contextgem.

Variables:

• message (str) – Human-readable error description

• retry_count (int or None) – Number of times that the model the error is for, i.e. the last model that was tried, was called again after it returned invalid data. The first call of the model, also of a fallback model, is not counted.

• original_error (Exception or None) – The underlying exception that caused the failure

Parameters:

• message (str)

• retry_count (int | None)

• original_error (Exception | None)

Initialize the exception.

Parameters:

• message (str) – Human-readable error description

• retry_count (int | None) – Number of retries attempted before failure

• original_error (Exception | None) – The underlying exception that caused the failure

exception contextgem.public.exceptions.LLMToolLoopLimitError(message, retry_count=None, original_error=None)

Bases: ContextGemError

Exception raised from a chat when the tool-calling loop reaches the configured tool_max_rounds limit and the LLM continues requesting tools.

Typically indicates that the LLM is stuck in a loop or needs more rounds to complete the workflow. Consider increasing tool_max_rounds or adjusting the tool instructions or the tool choice.

Can be imported from contextgem.

Initialize the exception.

Parameters:

• message (str) – Human-readable error description

• retry_count (int | None) – Number of retries attempted before failure

• original_error (Exception | None) – The underlying exception that caused the failure

exception contextgem.public.exceptions.ContextGemWarning

Bases: UserWarning

Category of the warnings that the framework issues for something in the calling code that will not have the expected effect, e.g. tools set on an LLM that is used for extraction, or an output language set together with a custom system message. Such a warning is attributed to the line of the calling code that caused it, where possible.

The warnings are Python warnings, not log messages, i.e. the logging level does not affect them. To filter them, use this category, e.g. warnings.filterwarnings("ignore", category=ContextGemWarning), or make them errors, e.g. in the tests of the calling code: a filter by the module of the framework does not match a warning attributed to the calling code. What happens while the framework runs, e.g. an extraction that fails when raise_exception_on_extraction_error=False is passed to the extraction method, is logged instead.

Can be imported from contextgem.