AdviceIT has two advisors, one per page, both learned from the same expert-validated data, and a set of explanation conditions built from two choices: what is explained (content) and how it is delivered (form). The advisor produces the recommendation. The explanation condition decides what the participant sees next to it. The scenario decides whether the advice shown is sound or deliberately flawed. Both advisors take the same profile, describe it with the same three suitability labels, and answer with one of the same six outcomes.
Shared vocabulary: suitability labels
Both advisors describe a profile with the three labels used by ILS-Bench, derived from the form by three documented rules. Risk tolerance is the stated Low / Medium / High (Moderate), or Inconsistent when a written description shows conflicting attitudes. Risk capacity counts what could force selling at a loss: no emergency fund, variable income, significant debt or obligations. None of them: High. One: Moderate. Two or more: Low. Liquidity need follows the horizon (1 to 2 years Urgent, 3 to 5 High, 6 to 10 Moderate, 11 or more Low), and a concrete near-term need makes it Urgent whatever the horizon. Age is the fourth input. These rules follow the dataset's codebook, which defines capacity by income, savings, debt and obligations, and liquidity by the need to access the funds soon.
Advisor 1: the AI advisor (neural network)
A multilayer perceptron (12 encoded inputs: the three suitability labels one-hot encoded plus age. The participant sets seven form fields, the label rules compress them to the labels, and the encoding expands the labels to 12 numbers. Two hidden layers of 16 units, 6 outputs) trained with ml/train_model.py on ILS-Bench (Bonelli 2026, Mendeley Data, CC BY 4.0): 400 investor narratives whose suitability labels and recommended outcome were validated by a panel of four financial-domain experts. The six outcomes are the five portfolios and Human review. Cross-validated accuracy is percent (5-fold, three repeats), on par with the dataset author's own draft labels and with a lookup table over the label combinations, and its probabilities are calibrated with temperature scaling. It runs in the browser from the exported weights in ml_weights.js. Its weights are not human-readable, so its explanations must be computed post hoc: exact Shapley values of the probability of the recommended outcome, the same counterfactual search, and calibrated probability for confidence.
Advisor 2: the interpretable rule-based advisor
A multinomial logistic regression fitted on the same ILS-Bench cases and the same twelve inputs as the network, percent cross-validated accuracy, calibrated with temperature scaling. It is a scorecard derived from data: one weight per input and outcome, the outcome with the largest total wins, and the contribution of each input to the evidence for the recommended outcome is read directly from the weights, exact and additive in log-odds. Same data and inputs as the network, but transparent. That is what makes explanation fidelity a factor: the same explanation styles are exact here and estimated on the AI advisor page.
Language to suitability
The ILS-Bench procedure starts from what an investor writes. The profile form therefore accepts a free-text description: the in-browser language model reads it into the form fields (age, horizon, tolerance, emergency fund, income) and flags an Inconsistent risk attitude when the text asks for high returns while saying that a loss would cause serious stress. The researcher can load any of the 400 benchmark cases and compare the advisors' outcome with the expert consensus for that case.
Explanation conditions: content and delivery
An explanation condition is a combination of content (what is explained: why, what would change it, how sure, in any combination or none) and delivery (how it is shown: static, interactive what-if, adaptive to literacy, or conversational). The Explanation control offers named presets for the common combinations, and Customise for any other. Both parts are recorded in the log.
- None: recommendation only.
- Why (feature-based): signed contribution of each input relative to the baseline profile. Exact log-odds contributions read from the weights for the interpretable rule-based advisor, exact Shapley values of the probability of the recommended outcome for the network.
- What would change it (counterfactual): the advisor is re-run over each input's range to find the smallest single change that flips the outcome. Works identically for both advisors.
- How sure (confidence): the calibrated probability of the recommended outcome with a bar per outcome.
- All three (hybrid): the three content parts together. Any other combination is a custom condition.
- Interactive what-if (delivery): a copy of the inputs the participant can move, with the outcome, the probabilities and the largest contributions updating live, "ignore this input" switches that hold an input at the neutral baseline, and a "why not X?" selector that gives a contrastive explanation (the smallest change that would give X, found by search), shown above whatever content is ticked. Moves and questions are counted in the log.
- Adaptive to literacy (delivery): the ticked content is shown as short plain sentences for a low Big Three literacy score, and as bars and probabilities for a high score. The three literacy questions appear in the profile form only with this delivery (and at the start of the full study flow). Falls back to the self-rating when the questions were not answered.
- Conversational (delivery): an open-weight language model (Llama 3.2 or Qwen 2.5) runs inside the browser on the GPU through WebLLM. It receives the ticked content, as computed by the other explanations, as its only source, writes a plain-language explanation, and answers follow-up questions. Its text is stored in the session log. Needs a WebGPU browser and the page served over http, not opened from a file.
The response
Under every recommendation the participant rates trust (1 to 7) and chooses Follow, Adjust, Reject or Ask a human adviser. Adjust asks which portfolio they would go for instead, and the log records it together with the number of steps from the shown portfolio. Three optional ratings (understanding, decision confidence, mental demand) and a free-text reason follow. Decision time runs from the moment the recommendation was shown.
The study flow
A participant link with flow=study runs the whole procedure: consent, the three literacy questions, six fixed hypothetical cases (half with sound and half with flawed advice, in an order seeded by the participant ID so it is reproducible), one attention check, and a debrief that names the flawed cases. The Analytics page then reads the collected responses.
Scenarios: sound and flawed advice
The Scenario control (researcher mode) or the scenario URL parameter (participant links) decides which advice is shown. Sound advice is the advisor's real outcome. Flawed advice takes that outcome and deliberately shifts it two portfolios in the wrong direction: conservative outcomes are pushed toward Aggressive growth, growth outcomes toward Capital preservation, and a Human review outcome is replaced by an automated portfolio two steps more aggressive than the score would justify. Two steps was chosen because one step is often still defensible, while two is a mistake a careful reader can catch.
The explanations always describe the advisor's real reasoning, so in the flawed scenario the explanation and the recommendation do not fit together. Whether participants notice, and whether the explanation style helps them notice, is exactly what the study measures. Every logged response records the scenario, the portfolio that was shown and the sound portfolio, so appropriate reliance can be computed per condition: the follow rate on sound advice and the override rate (Adjust or Reject) on flawed advice. Following flawed advice is over-reliance, rejecting sound advice is under-reliance. In researcher mode an amber note marks a flawed recommendation. Participants never see that note, and a real study debriefs them about the flawed trials afterwards.
The full source is readable in model.js (label rules), ml_model.js, logit_model.js, explanations.js, llm.js and ml/train_model.py.