Chat Session State#

API Reference > Chat > Chat Session State

The chat session state classes represent the current state and configuration of an active chat session with DecisionAI. These classes contain information about the optimization model being built, constraints, variables, and other session-specific data.

Purpose:

Track the current state of a chat session
Store optimization model components as they’re built
Manage constraint priorities and soft constraints
Provide access to session metadata

ChatSessionState#

The main class representing the complete state of a chat session.

class decision_ai.client.schemas.chat_session.ChatSessionState(*, id: str, opt_model_id: str, opt_input_data_id: str, created_at: int, updated_at: int, py_class_name_of_model: str, py_class_name_of_input_data: str, executive_summary: str, constraints: dict[str, Constraint], variables: dict[str, Variable], objective: Objective, opt_model_notations: OptModelNotations, input_data_classes: list[str] | None = None, reasoning_enabled: bool | None = None)#

Bases: BaseModel

State of a chat session containing information about the optimization model.

Contains variables, constraints, objective, model notation, and summary.

make_constraints_soft() → None#: Enable soft constraints.

Deprecated since version 0.14.0-rc.2: Use set_constraint_priority on individual constraints instead.

make_constraints_hard() → None#: Disable soft constraints.

Deprecated since version 0.14.0-rc.2: Use set_constraint_priority on individual constraints instead.

property base_variable_ids: set[str]#

Get the set of IDs for all base variables.

A base variable is a variable that is contained in the originally deployed optimization model and was not added by a user via DecisionAI.

Returns:: Set of IDs for all base variables
Return type:: set[str]

property user_variable_ids: set[str]#

Get the set of IDs for all user-defined variables.

A user-defined variable is a variable that was added by a user via DecisionAI.

Returns:: Set of IDs for all user-defined variables
Return type:: set[str]

property variable_descriptions: dict[str, str]#

Get descriptions for all variables.

Returns:: Dictionary mapping variable IDs to their descriptions
Return type:: dict[str, str]

property base_variable_descriptions: dict[str, str]#

Get descriptions for base variables.

A base variable is a variable that is contained in the originally deployed optimization model and was not added by a user via DecisionAI.

Returns:: Dictionary mapping base variable IDs to their descriptions
Return type:: dict[str, str]

property user_variable_descriptions: dict[str, str]#

Get descriptions for user-defined variables.

A user-defined variable is a variable that was added by a user via DecisionAI.

Returns:: Dictionary mapping user-defined variable IDs to their descriptions
Return type:: dict[str, str]

is_variable_active(id_: str) → bool#

Check if a variable is active.

Parameters:: id (str) – ID of the variable to check

Deprecated since version 0.14.0-rc.2: Use is_variable_enabled instead.

is_variable_enabled(id_: str) → bool#

Check if a variable is active, i.e. is being used when the model is formulaized.

Parameters:: id (str) – ID of the variable to check
Returns:: True if the variable is active, False otherwise
Return type:: bool

mark_variable_as_inactive(id_: str) → None#

Mark a variable as inactive.

Parameters:: id (str) – ID of the variable to mark as inactive

Deprecated since version 0.14.0-rc.2: Use disable_variable instead.

disable_variable(id_: str) → None#

Mark a variable as inactive, i.e. is not being used when the model is formulaized.

Parameters:: id (str) – ID of the variable to mark as inactive
Raises:: KeyError – If the variable does not exist

mark_variable_as_active(id_: str) → None#

Mark a variable as active.

Parameters:: id (str) – ID of the variable to mark as active

Deprecated since version 0.14.0-rc.2: Use enable_variable instead.

enable_variable(id_: str) → None#

Mark a variable as active, i.e. is being used when the model is formulaized.

Parameters:: id (str) – ID of the variable to mark as active
Raises:: KeyError – If the variable does not exist

add_variable(id_: str, code: str, type_hint: str, description: str = '') → None#

Add a new variable to the model.

Parameters:

id (str) – ID of the variable to add
code (str) – Code of the variable
type_hint (str) – Type hint of the variable
description (str) – Description of the variable

Raises:

KeyError – If the variable already exists
ValidationError – If the type of one of the parameters is not valid.

replace_variable(id_: str, code: str, type_hint: str, description: str = '') → None#

Replace an existing variable with new code.

Parameters:

id (str) – ID of the variable to replace
code (str) – Code of the variable
type_hint (str) – Type hint of the variable
description (str) – Description of the variable

Raises:

KeyError – If the variable does not exist
ValidationError – If the type of one of the parameters is not valid.

remove_variable(id_: str) → None#

Remove a variable from the model.

Parameters:: id (str) – ID of the variable to remove
Raises:: KeyError – If the variable does not exist

property constraint_ids: set[str]#

Get the set of IDs for all constraints.

Returns:: Set of IDs for all constraints
Return type:: set[str]

property base_constraint_ids: set[str]#

Get the set of IDs for all base constraints.

A base constraint is a constraint that is contained in the originally deployed optimization model and was not added by a user via DecisionAI.

Returns:: Set of IDs for all base constraints
Return type:: set[str]

property user_constraint_ids: set[str]#

Get the set of IDs for all user-defined constraints.

A user-defined constraint is a constraint that was added by a user via DecisionAI.

Returns:: Set of IDs for all user-defined constraints
Return type:: set[str]

property incompatible_constraint_ids: set[str]#

Get the set of IDs for all incompatible constraints.

Returns:: Set of IDs for all incompatible constraints
Return type:: set[str]

property constraint_descriptions: dict[str, str]#

Get descriptions for all constraints.

Returns:: Dictionary mapping constraint IDs to their descriptions
Return type:: dict[str, str]

property base_constraint_descriptions: dict[str, str]#

Get descriptions for base constraints.

A base constraint is a constraint that is contained in the originally deployed optimization model and was not added by a user via DecisionAI.

Returns:: Dictionary mapping base constraint IDs to their descriptions
Return type:: dict[str, str]

property user_constraint_descriptions: dict[str, str]#

Get descriptions for user-defined constraints.

A user-defined constraint is a constraint that was added by a user via DecisionAI.

Returns:: Dictionary mapping user-defined constraint IDs to their descriptions
Return type:: dict[str, str]

is_constraint_active(id_: str) → bool#

Check if a constraint is active.

Parameters:: id (str) – ID of the constraint to check

Deprecated since version 0.14.0-rc.2: Use is_constraint_enabled instead.

is_constraint_enabled(id_: str) → bool#

Check if a constraint is active, i.e. is being used when the model is formulaized.

Parameters:: id (str) – ID of the constraint to check
Returns:: True if the constraint is active, False otherwise
Return type:: bool
Raises:: KeyError – If the constraint does not exist

mark_constraint_as_inactive(id_: str) → None#

Mark a constraint as inactive.

Parameters:: id (str) – ID of the constraint to mark as inactive

Deprecated since version 0.14.0-rc.2: Use disable_constraint instead.

disable_constraint(id_: str) → None#

Mark a constraint as inactive, i.e. is not being used when the model is formulaized.

Parameters:: id (str) – ID of the constraint to mark as inactive
Raises:: KeyError – If the constraint does not exist

mark_constraint_as_active(id_: str) → None#

Mark a constraint as active.

Parameters:: id (str) – ID of the constraint to mark as active

Deprecated since version 0.14.0-rc.2: Use enable_constraint instead.

enable_constraint(id_: str) → None#

Mark a constraint as active, i.e. is being used when the model is formulaized.

Parameters:: id (str) – ID of the constraint to mark as active
Raises:: KeyError – If the constraint does not exist

add_constraint(id_: str, code: str, math_formulation: str = '', description: str = '', priority: Literal['hard', 'A', 'B', 'C'] = 'hard') → None#

Add a new constraint to the model.

Parameters:

id (str) – ID of the constraint to add
code (str) – Code of the constraint
math_formulation (str, optional) – Mathematical formulation of the constraint. Defaults to “”.
description (str, optional) – Description of the constraint. Defaults to “”.
priority (Priority) – The priority level for soft constraints. Defaults to “hard”.

Raises:

KeyError – If the constraint already exists
ValidationError – If the type of one of the parameters is not valid.

replace_constraint(id_: str, code: str, math_formulation: str | None = None, description: str = '') → None#

Replace an existing constraint with new code.

Parameters:

id (str) – ID of the constraint to replace
code (str) – Code of the constraint
math_formulation (str | None) – Mathematical formulation of the constraint
description (str) – Description of the constraint

Raises:

KeyError – If the constraint does not exist
ValidationError – If the type of one of the parameters is not valid.

remove_constraint(id_: str) → None#

Remove a constraint from the model.

Parameters:: id (str) – ID of the constraint to remove
Raises:: KeyError – If the constraint does not exist

replace_objective(code: str, math_formulation: str | None = None, description: str = '') → None#

Replace the objective function with new code.

Parameters:

code (str) – Code of the objective function
math_formulation (str | None, optional) – Mathematical formulation of the objective function. Defaults to None.
description (str, optional) – Description of the objective function. Defaults to “”.

Raises:

ModelParseError – If the code contains a ‘return’ statement or a ‘def’ statement

get_constraint_code(id_: str) → str#

Get the code for a specific constraint.

Parameters:: id (str) – ID of the constraint to get the code for
Returns:: Code for the constraint
Return type:: str
Raises:: KeyError – If the constraint does not exist

get_constraint_formulation(id_: str) → str#

Get the mathematical formulation for a specific constraint.

Parameters:: id (str) – ID of the constraint to get the mathematical formulation for
Returns:: Mathematical formulation for the constraint
Return type:: str
Raises:: KeyError – If the constraint does not exist

set_constraint_priority(id_: str, priority: Literal['hard', 'A', 'B', 'C']) → None#

Set the priority level for a constraint.

Parameters:

id (str) – ID of the constraint to set the priority for
priority (Priority) – Priority level to set (“hard”, “A”, “B”, or “C”)

Raises:

KeyError – If the constraint does not exist

get_constraint_priority(id_: str) → Literal['hard', 'A', 'B', 'C']#

Get the priority level for a constraint.

Parameters:: id (str) – ID of the constraint to get the priority for
Returns:: Priority level of the constraint (“hard”, “A”, “B”, or “C”)
Return type:: Priority
Raises:: KeyError – If the constraint does not exist

set_soft_constraint_priority(id_: str, priority: Literal['hard', 'A', 'B', 'C']) → None#

Set the priority of a soft constraint.

Parameters:

id (str) – ID of the constraint to set the priority for
priority (Priority) – Priority to set

Deprecated since version 0.14.0-rc.2: Use set_constraint_priority instead.

get_ids_with_missing_mathematical_formulation() → list[str]#: Get IDs of constraints missing mathematical formulation.

get_mathematical_formulation() → str#

Get the complete mathematical formulation of the model.

Returns:: Complete mathematical formulation of the model
Return type:: str
Raises:: PropertyNotAvailableError – If the mathematical formulation is not available

property variable_notations: list[Notation]#

Get the list of variable notations generated from variables.

Returns:: List of variable notations
Return type:: list[Notation]

property input_notations: list[Notation]#

Get the list of input notations.

Returns:: List of input notations
Return type:: list[Notation]
Raises:: PropertyNotAvailableError – If the model notation state is not available

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

update_model_incompatibilities(error_report: FormulationErrorReport | str) → None#

Update the model incompatibilities.

Parameters:: error_report (FormulationErrorReport | str) – The error report to update the model incompatibilities with. If a string is provided, it is used as the incompatibility reason for the objective and all constraints.

Key Properties:

Model Information - Current optimization model structure
Variables - Defined optimization variables
Constraints - Hard and soft constraints
Objective - Current objective function
Metadata - Session configuration and settings

Usage Example#

# Access session state from a chat session
session = client.create_chat_session()

# After interacting and building a model
state = session.get_session_state()

# Access model components
print(f"Variables: {state.variables}")
print(f"Constraints: {state.constraints}")
print(f"Objective: {state.objective}")

Working with Soft Constraints#

The ChatSessionState class provides methods to work with soft constraints and their priorities.

# Set constraint priorities (recommended way)
state.set_constraint_priority("constraint_id", "A")  # High priority
state.set_constraint_priority("another_id", "B")     # Medium priority
state.set_constraint_priority("third_id", "C")       # Low priority

# Check constraint priorities
for constraint_id in state.constraint_ids:
    priority = state.get_constraint_priority(constraint_id)
    print(f"Constraint {constraint_id}: Priority {priority}")

# Enable/disable constraints (recommended way)
state.enable_constraint("constraint_id")
state.disable_constraint("another_id")

# Deprecated methods (will be removed in future versions):
# state.make_constraints_soft()      -> Use set_constraint_priority() instead
# state.make_constraints_hard()      -> Use set_constraint_priority() instead
# state.is_constraint_active()       -> Use is_constraint_enabled() instead
# state.mark_constraint_as_active()  -> Use enable_constraint() instead
# state.mark_constraint_as_inactive()-> Use disable_constraint() instead

Working with Variables#

The ChatSessionState class provides methods to manage variables.

# Enable/disable variables (recommended way)
state.enable_variable("variable_id")
state.disable_variable("another_variable_id")

# Check variable state (recommended way)
for var_id in state.variable_ids:
    enabled = state.is_variable_enabled(var_id)
    print(f"Variable {var_id}: {'Enabled' if enabled else 'Disabled'}")

# Deprecated methods (will be removed in future versions):
# state.is_variable_active()       -> Use is_variable_enabled() instead
# state.mark_variable_as_active()  -> Use enable_variable() instead
# state.mark_variable_as_inactive()-> Use disable_variable() instead

Common Use Cases#

Session State Inspection:

def inspect_session_state(session):
    """Inspect the current state of a chat session."""
    state = session.get_session_state()

    print(f"Session has {len(state.variables)} variables")
    print(f"Session has {len(state.constraints)} constraints")

    if state.objective:
        print(f"Objective: {state.objective.code}")

    # Print constraints by priority
    for priority in ["hard", "A", "B", "C"]:
        count = sum(1 for c in state.constraints.values() if c.priority == priority)
        print(f"{priority} constraints: {count}")

State-Based Decision Making:

def can_solve_model(session_state):
    """Check if the model is ready to solve."""
    return (
        len(session_state.variables) > 0 and
        len(session_state.constraints) > 0 and
        session_state.objective is not None
    )

Back to: API Reference (API Reference Overview)