Is it possible to customize the Suggestions Bar?

Question

I'd like to be able to customize the Suggestions Bar in v9.0 to provide recommendations of my own. Possible example: when doing unit calculations, I'd like it to suggest converting the answer to reduced SI units, or whatever class of units are appropriate.

My idea is to use the Suggestions Bar interface to lead a student along a path of self-discovery by leaving the right breadcrumbs at the right time.

I didn't see anything in the documentation... is this possible? Or should I implement some other interactive feature to get the same result: like an embedded palette?

Answer 1

Yes! It is possible, although it takes some spelunking.

Upon some searching with Names, I came across three relevant contexts where the predictive interface functions live: PredictiveInterface`, PredictiveInterfaceDump`, and Predictions`. This last one is where the action happens.

Luckily, the symbols were only ReadProtected, and their source code was readily available using Definition.

The main function that generates the predictions is Predictions`MakePredictions. Inside the function, a semantic type is generated based on the previous input and output cells, along with an attribute vector that holds some extra information about the expression, and then the relevant predictive actions are chosen based on that type. The type generation comes from the function Predictions`Private`AttributeVectorAndSemanticTypes.

The list of all the types with their corresponding action names exists in the form of a Dispatch table in Predictions`Private`PredictionRuleNameRules. Entries in this list have the form type_ -> actionNames_List. For example, the "Quantity" type entry looks like this:

"Quantity" -> {"QuantityMagnitude", "QuantityUnit", "NumericalValue", "QuantityDimensions", "UnitConvertToSystem", "UnitConvertToUnit", "UnitSimplify", "QuantityForm"}

where each of the strings in the list on the right-hand side is the name of an action.

Once a type is chosen and its corresponding action names have been found, the action is called using Predictions`PredictionRule. Predictions`PredictionRule has many DownValues for all the relevant combinations of action name and attribute vector. The general form of the function is

Predictions`PredictionRule[actionName_, attributeVector_List, Predictions`InOut[in_, out_]]

It looks like the generic attribute vector pattern is

$genericAttributeVectorPattern = ConstantArray[_, 255];

Predictions`PredictionRule returns a Predictions`Prediction object, which has the form

Predictions`Prediction[
    rank_,
    categoryLabel_,
    actionLabel_,
    action_
]

where rank is some type of score, categoryLabel and actionLabel are strings for front-end displaying, and action is a function that takes in the previous cell's input and output. For example, the generic Predictions`Prediction for "QuantityMagnitude" is

Predictions`Prediction[
    0.6`,
    Predictions`ruleTextResource["categoryQuantities"], 
    Predictions`ruleTextResource["actionMagnitude"], 
    HoldComplete[QuantityMagnitude[#2]] &
]

The text resource strings are stored in

$predictiveInterfaceRuleStringsPath = FileNameJoin[{$UserBaseDirectory, "Paclets", "Repository", "PredictiveInterface-Mac-2.3.0", "FrontEnd", "TextResources", "PredictiveRuleStrings.tr"}];

where you should replace "PredictiveInterface-Mac-2.3.0" with your corresponding OS and version.

So, to add a new predictive action (using an existing type):

1. Add your new action name to the Dispatch table in Predictions`Private`PredictionRuleNameRules:

   addPredictionRuleName[type_String, name_String] := Block[{oldNameRules, newNameRules},
       oldNameRules = Predictions`Private`PredictionRuleNameRules[];
       newNameRules = oldNameRules[[1]] /. HoldPattern[type -> {names___}] :> (type -> DeleteDuplicates[{names, name}]);
       Predictions`Private`PredictionRuleNameRules[] = Dispatch[newNameRules];
   ]
   

   For example, calling addPredictionRuleName["Quantity", "QuantityTimesTwo"] will add a new action name "QuantityTimesTwo" under the type "Quantity".

2. Add a new DownValue to Predictions`PredictionRule for your action name. For example:

   Predictions`PredictionRule[
       "QuantityTimesTwo",
       $genericAttributeVectorPattern, 
       Predictions`InOut[in_, out_]
   ] := Predictions`Prediction[
            0.9,
            "quantities",
            "quantity times two",
            HoldComplete[2*#2] &
   ]
   

That's it! I haven't played with adding new types to the system, but I'm sure that's possible too.