Narrative explanations (using LLMs)

LLMs make it possible to convert your explanations into readable, natural-language sentences.

The full code for this and all other user guides can be found in our user guide tutorial.

Installation

To use narrative explanation functions, you will need to install Pyreal with the extra LLM dependencies:

pip install pyreal[llm]

Narrative Explanations

You may prefer to get explanations in natural-language sentences. For example, instead of a table or graph of feature contributions, you may prefer what we call a narrative explanation:

The predicted price of the house increased significantly (by about $20,000) because of its location in the expensive neighborhood of Sawyer. However, the house is smaller than average (at 605 sq. ft.) and does not have AC, which reduced its predicted price by about $12,000.

To generate narrative explanations accurately, we plug the explanations generated by Pyreal into a large language model (LLM), which automatically converts it into sentence format.

Currently, Pyreal requires an OpenAI API key to use its narrative explanation functionality, which will incur a cost. We hope to add free options for this functionality soon!

To generate narrative explanations, you can either pass your API key into your RealApp at initialization, or to the produce function.

At the moment, the only supported narrative explanation function is .produce_narrative_feature_contributions, which generates a feature contributions explanation in sentence format.

realapp.set_openai_client(openai_api_key="YOUR_OPENAI_KEY")
narratives = realapp.produce_narrative_feature_contributions(x_input)

narratives["House 101"]
# Sample output: 
# The model predicts a lower price for a house with average quality 
# finishing and materials and a smaller above ground living area...

Tuning narratives

There are several key input parameters to the produce_narrative_feature_contributions function when tuning your narrative explanations:

• num_features (int, default=5): the number of features to include in the narrative.

• llm_model (one of "gpt3.5", "gpt4", default="gpt3.5"): the LLM model to use. GPT4 may produce better narratives, but will be more expensive.

• detail_level (one of "high", "low", default="high): high detail narratives will explicitly list all contribution values, while low detail will tend to discuss only the general contribution direction. You can tune this further with training, see the Improving Narratives section on this page.

• context_description (string): A brief sentence explaining what the model does. For example, "The model predicts the price of houses". This can also be passed into the RealApp object at initialization instead.

• max_tokens (int, default=200): The maximum number of tokens to include in the explanation narratives. Larger values allow for longer narratives, but may cost more. Larger num_feature values require more tokens (roughly 40 tokens per feature seems to work well).

Improving Narratives

You can train the LLM on what kinds of explanations you want. This is called few-shot learning. The LLM asks you for some examples of explanations, and then learns from those examples.

To run this training, you can use the .train_feature_contribution_llm. This function will show a few feature contributions explanations, and ask you for narrative versions using Python input/output.

For example, let's say you want very basic explanations that just list out important features:

# num_inputs -> the number of explanations to show and ask for narrative versions of
#               you will probably see results with ~3-5 inputs.
# num_features -> the number of features to include per explanation.
realapp.train_feature_contribution_llm(num_inputs=2, num_features=2)

The function above will trigger an I/O chain:

PYREAL: For each of the following inputs, please provide an appropriate narrative version.

PYREAL: Input 1 (feature, value, contribution): (Lot size, 1039, 1230), (Material, Brick, 2930)

PYREAL: Narrative explanation ('q' to quit):

USER: The house's predicted price increased because of its lot size and material

PYREAL: Input 2 (feature, value, contribution): (AC, No, -1320), (Location, Sawyer, 4306)

PYREAL: Narrative explanation ('q' to quit):

USER: The lack of AC reduced the predicted price, while the location increased it.

Future narrative explanations generated by this RealApp will now mirror the structure of the user-given examples - in this case, by mentioning important features and their direction of contribution.