PulpDecisionAIModel

API Reference > Modeling > PulpDecisionAIModel

The decision_ai.PulpDecisionAIModel class is the heart of the DecisionAI package. This is the base class that your optimization problem must inherit from to work with DecisionAI.

Key Features:

• Define optimization problems using familiar PuLP syntax

• Automatic integration with DecisionAI’s chat interface

• Support for constraint priorities and soft constraints

• Built-in solution parsing and formatting

Core Workflow:

1. Inherit from PulpDecisionAIModel

2. Define your variables class (inheriting from decision_ai.PulpVariables)

3. Implement constraint methods using the decision_ai.constraint() decorator

4. Set the objective function

5. Connect with DecisionAI for interactive optimization

Quick Start Example

from decision_ai import PulpDecisionAIModel, PulpVariables, InputData, constraint
import pulp as pl

class MyInputData(InputData):
    num_items: int
    capacity: int

class MyVariables(PulpVariables):
    def init_x(self, input_data: MyInputData) -> dict:
        return {
            i: pl.LpVariable(f"x_{i}", cat='Binary')
            for i in range(input_data.num_items)
        }

class MyOptimizationModel(PulpDecisionAIModel):
    variables_class = MyVariables

    @constraint
    def capacity_constraint(input_data: MyInputData, variables: MyVariables) -> pl.LpConstraint:
        return pl.lpSum(variables.x[i] for i in range(input_data.num_items)) <= input_data.capacity

    def set_objective(self, input_data: MyInputData) -> None:
        self.problem += pl.lpSum(self.variables.x[i] for i in range(input_data.num_items))

Class Reference

class decision_ai.PulpDecisionAIModel

Bases: Generic[GenericInput, GenericVariables], ABC

Model interface class. Custom optimization models inherit from this class.

set_up_constraints(input_: GenericInput, prob: LpProblem, variables: GenericVariables, constraint_id_to_name: dict[str, list[str]], add_constraints: list[str] | None | Literal['all'] = None, delete_constraints: list[str] | None = None) → tuple[LpProblem, dict[str, list[str]]]

Set up the constraints of the model.

This method gathers all the methods with the constraint decorator, calls the methods, and adds the constraints to the problem.

abstractmethod set_up_objective(input_: GenericInput, prob: LpProblem, variables: GenericVariables) → LpProblem

This method defines the objective function and adds it to the problem.

abstractmethod solution_to_str(input_: GenericInput, solution: Solution) → str

This method converts the solution to a human-readable string.

find_variables_class() → type[GenericVariables]

Look in the current namespace for a class that inherits from PulpVariables.

formulate(input_: GenericInput, add_constraints: list[str] | None | Literal['all'] = 'all') → tuple[GenericVariables, LpProblem, dict[str, list[str]]]

Formulate the optimization problem.

This method sets up the variables, objective, and constraints of the optimization problem.

Parameters:

• input – The input of the model.

• add_constraints – List of constraint IDs to add to the problem.

Returns:

Formulated problem.

The tuple contains the variables, the problem, and a dictionary mapping constraint names to constraint group IDs. A constraint group ID is the name of the function yielding the constraints.

Return type:

tuple[GenericVariables, pulp.LpProblem, dict[str, list[str]]]

find_feasible_solution(prob: LpProblem, variables: GenericVariables) → Solution[GenericVariables]

Run CBC to find a feasible solution.

The solver is stopped as soon as a feasible solution is found.

Parameters:

• prob – The PuLP problem object.

• variables – The variables of the model.

Returns:

A solution object with the status, objective, variables, and violated constraints.

solve(prob: LpProblem, variables: GenericVariables, input_: GenericInput, **kwargs) → Solution[GenericVariables]

Solve the optimization problem using the Quantagonia hybrid solver. This method can be overriden by the user to implement a custom solver.

Parameters:

• prob – The PuLP problem object.

• variables – The variables of the model.

• input – The input data of the model.

• **kwargs – Optional solver parameters: time_limit: Maximum solving time in seconds integrality_tolerance: Tolerance for integer variables feasibility_tolerance: Tolerance for constraint violations relative_gap: Relative optimality gap absolute_gap: Absolute optimality gap presolve: Enable/disable presolve (boolean) seed: Random seed for reproducibility heuristics_only: Use only heuristic methods (boolean) objective_limit: Upper bound on objective value

Returns:

A solution object with the status, objective, variables, and violated constraints.

Back to: API Reference (API Reference Overview)