Data models

Data models#

Module defining public data validation models.

class contextgem.public.data_models.LLMPricing(**data)[source]#

Bases: _InstanceSerializer

Represents the pricing details for an LLM.

Defines the cost structure for processing input tokens and generating output tokens, with prices specified per million tokens.

Variables:

input_per_1m_tokens – The cost in currency units for processing 1M input tokens.
output_per_1m_tokens – The cost in currency units for generating 1M output tokens.

Parameters:

input_per_1m_tokens (StrictFloat)
output_per_1m_tokens (StrictFloat)

Example:

LLM pricing definition#

from contextgem import LLMPricing

# Create a pricing model for an LLM (openai/o3-mini example)
pricing = LLMPricing(
    input_per_1m_tokens=1.10,  # $1.10 per million input tokens
    output_per_1m_tokens=4.40,  # $4.40 per million output tokens
)

# LLMPricing objects are immutable
try:
    pricing.input_per_1m_tokens = 0.7
except ValueError as e:
    print(f"Error when trying to modify pricing: {e}")

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

input_per_1m_tokens: typing.Annotated[float]#

output_per_1m_tokens: typing.Annotated[float]#

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.

Parameters:: obj_dict (dict[str, Any]) – Dictionary containing the serialized object data.
Returns:: A new instance of the class with restored attributes.
Return type:: 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) – Path to the JSON file to load (must end with ‘.json’).

Returns:

An instance of the class populated with the data from the file.

Return type:

Self

Raises:

ValueError – If the file path doesn’t end with ‘.json’.
OSError – If there’s an error reading the file.
RuntimeError – If deserialization fails.

classmethod from_json(json_string)#

Creates an instance of the class from a JSON string representation.

This method deserializes the provided JSON string into a dictionary and uses the from_dict method to construct the class instance. It validates that the class name in the serialized data matches the current class.

Parameters:: json_string (str) – JSON string containing the serialized object data.
Returns:: A new instance of the class with restored state.
Return type:: Self
Raises:: 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 an LLM or LLM group is serialized, its API credentials and usage/cost stats are removed.

Returns:: A dictionary representation of the current object with all necessary data for serialization
Return type:: dict[str, 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) – Path where the JSON file should be saved (must end with ‘.json’).

Return type:

None

Returns:

None

Raises:

ValueError – If the file path doesn’t end with ‘.json’.
IOError – If there’s an error during the file writing process.

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

class contextgem.public.data_models.RatingScale(**data)[source]#

Bases: _InstanceSerializer

Represents a rating scale with defined minimum and maximum values.

This class defines a numerical scale for rating concepts, with configurable start and end values that determine the valid range for ratings.

Variables:

start – The minimum value of the rating scale (inclusive). Must be greater than or equal to 0.
end – The maximum value of the rating scale (inclusive). Must be greater than 0.

Parameters:

start (StrictInt)
end (StrictInt)

Example:

Rating scale definition#

from contextgem import RatingScale

# Create a rating scale with default values (0 to 10)
default_scale = RatingScale()

# Create a custom rating scale (1 to 5)
custom_scale = RatingScale(
    start=1,
    end=5,
)

# RatingScale objects are immutable
try:
    custom_scale.end = 7
except ValueError as e:
    print(f"Error when trying to modify rating scale: {e}")

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

start: typing.Annotated[int]#

end: typing.Annotated[int]#

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.

Parameters:: obj_dict (dict[str, Any]) – Dictionary containing the serialized object data.
Returns:: A new instance of the class with restored attributes.
Return type:: 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) – Path to the JSON file to load (must end with ‘.json’).

Returns:

An instance of the class populated with the data from the file.

Return type:

Self

Raises:

ValueError – If the file path doesn’t end with ‘.json’.
OSError – If there’s an error reading the file.
RuntimeError – If deserialization fails.

classmethod from_json(json_string)#

Creates an instance of the class from a JSON string representation.

This method deserializes the provided JSON string into a dictionary and uses the from_dict method to construct the class instance. It validates that the class name in the serialized data matches the current class.

Parameters:: json_string (str) – JSON string containing the serialized object data.
Returns:: A new instance of the class with restored state.
Return type:: Self
Raises:: 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 an LLM or LLM group is serialized, its API credentials and usage/cost stats are removed.

Returns:: A dictionary representation of the current object with all necessary data for serialization
Return type:: dict[str, 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) – Path where the JSON file should be saved (must end with ‘.json’).

Return type:

None

Returns:

None

Raises:

ValueError – If the file path doesn’t end with ‘.json’.
IOError – If there’s an error during the file writing process.

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

Data models

Contents

Data models#