ActionCue: Uncertainty-to-action binding

Manuscript

Visualizing Uncertainty-to-Action Composition for Human Oversight

Authored by: Chisom Anyabolu, Akshat Dubey, Georges Hattab

Please cite the following article should you use any part of this code or build upon it:

citation placeholer

Abstract

Artificial intelligence systems often disclose uncertainty, yet they rarely make clear what response that uncertainty should trigger. Most uncertainty visualization encodes uncertainty in model output, leaving users to discern the most appropriate course of action. A second region of the design space--uncertainty in the decision process itself, including how multiple uncertainty conditions compose into an oversight response-- remains comparatively underexplored. We address this gap with two coupled contributions. First, we introduce an uncertainty-to-action binding framework that composes multiple uncertainty conditions into a single oversight response under a precedence policy with a contextual safety modifier. That response concerns whether and how an AI-supported decision may proceed, not the substantive domain decision itself. Second, we present ActionCue, a process-transparency visualization that renders that composition explicit. We demonstrate the approach through a three-way comparison with confidence-only and data-level uncertainty displays, using worked cases from healthcare, credit assessment, and disaster forecasting. Together, the framework specifies how uncertainty conditions are resolved into an oversight response, and the visualization makes that resolution inspectable rather than implicit.

Dependencies

Dependency	Version
Python	3.11+
streamlit	latest
pytest	latest

Full pin list in requirements.txt. No external API calls, no model loading, no network — the prototype is fully offline and deterministic.

Data

The prototype runs on seven synthetic decision cases stipulated as Python objects. No external data files are read.

Location	Description
cases/healthcare.py	CASE_A–CASE_E: clinical decisions covering proceed, sensitivity-driven inspection, completion-wins-precedence, validity-escalation, and safety-modifier-lifted abstention.
cases/cross_domain.py	CASE_CR (credit risk, validity dominates completion) and CASE_DR (disaster forecasting, sensitivity with safety lift).

Case	Domain	Behavior
CASE_A	healthcare	No rules fire → proceed / advisory.
CASE_B	healthcare	Sensitivity fires → inspect / strong.
CASE_C	healthcare	Completion wins precedence over sensitivity → complete / mandatory.
CASE_D	healthcare	Validity fires → escalate / mandatory.
CASE_E	healthcare	Validity + high harm + low reversibility → abstain / blocking (safety lift).
CASE_CR	credit risk	Validity dominates completion → escalate / mandatory.
CASE_DR	disaster	Sensitivity under high-harm / low-reversibility context → inspect / mandatory (safety lift).

Code

Location	Description
models.py	Dataclasses: Case, Rule, UncertaintySignal, RuleFiring, Cue.
rules.py	The four rule definitions (RULES) and the signal_for resolver.
engine.py	Rule firing, constraint-matrix validation, precedence resolution, safety modifier, compose_cue.
viz/	SVG renderers (case input, signals, cascade) + the two compositors. Each renderer is pure: takes a Case / Cue, returns a string.
ui/	Streamlit wrappers — thin pass-throughs to components.html. No SVG generation, no engine logic.
app.py	Streamlit entry point: page config, mode + case selectors, layout.
export_figures.py	Offline figure generator. Produces the six paper figures + an HTML index without launching Streamlit.
tests/test_engine.py	11 tests: one per case plus engine invariants.
SPEC.md	Full build specification: data models, panel specs, rule definitions, color tokens (§9).

Force levels: advisory, strong, mandatory, blocking. The CVD-deliberate color palette (deep navy + vermillion ramp for force; Wong 2011 categorical hues for rule class) is documented.

Installation and running

Setup

# Python 3.11+ required.
pip install -r requirements.txt

Engine tests

pytest tests/

11 tests, ~10ms. Pass means the rule engine, constraint matrix, precedence resolution, and safety modifier all behave as intended.

Live demo

streamlit run app.py

Opens at http://localhost:8501. The sidebar exposes two view modes and a case selector:

• ActionCue (full). Three-panel layout: case input + signals on the top row, the annotated cascade full-width below. The cascade carries the cue display, force strip, and safety banner inline. Hover the resolution arrow and the strip-safety arrow for tooltips; click a fired band to reveal its rationale and triggering signal.
• Three-way comparison. Three side-by-side columns: confidence-only, data-level uncertainty (interval bar with threshold marked, same renderer as Panel 1), and the ActionCue cascade. CASE_C is the recommended starting case — confidence-only says "act"; uncertainty-only says "borderline"; ActionCue surfaces the missing input as the primary issue.

A rules registry expander at the bottom of the page shows the four rule definitions — same data the engine reads — with precedence, class, base action, base force, bound signal, and description.

License

Released under the MIT License — see LICENSE.