Governance Studio dashboard

HUGIML Governance Studio provides a Dash interface for preparing data, configuring HUGIML and RPTE runs, comparing candidate models, reviewing model evidence, and assembling governance-ready summaries. The existing lightweight Streamlit interface remains available. Both interfaces use the same model, runner, and governance evidence layers.

Installation and launch

Install the dashboard optional dependencies, then launch the installed console command:

pip install "hugiml-core[dashboard]"
hugiml-dashboard                    # Dash, the default interface
hugiml-dashboard --ui light         # lightweight Streamlit interface

The launcher accepts --host, --port, --debug, --no-open, --cv, and --random-state. For source-tree development, the interfaces can also be launched directly:

python -m hugiml.dashboard.dash_app
python -m streamlit run src/hugiml/dashboard/app.py

Workbench workflow

• Choose a demo dataset or upload a tabular file.

• Review the compact dataset preview, expand the on-demand data profile, and adjust target, identifier, protected, date, numeric, categorical, and excluded columns.

• Configure HUGIML, the optional RPTE downstream model, and comparison models; advanced controls include adaptive binning, representation choices, and RPTE tree-growth settings.

• Run a single configuration or a small candidate grid.

• Compare models using validation metrics and timing information.

• Inspect feature roles, pattern evidence, case-level explanations, policy checks, and governance summaries.

Data profiling

The Setup area includes a compact preview followed by a collapsed profiling section. Expanding the section computes the profile only when it is needed. The default sample is deterministic and limited to 10,000 rows; the full-data option is available when the selected dataset is larger than that limit.

Two views serve different review purposes:

Raw data

Profiles the uploaded or selected dataset as supplied, including target, identifiers, protected fields, dates, predictors, and excluded columns.

Model input

Profiles only the columns that remain eligible for model preparation after target, identifier, protected, date, and excluded roles are applied. The profile states which columns were removed and why.

The profile includes dataset-level quality findings, variable roles and semantic types, missingness patterns, numeric and categorical distributions, correlation summaries, and target associations when a valid target is selected. The same registered source frame is reused during model preparation so the preview, profile, and experiment runner refer to the same rows.

Evidence views

The dashboard includes the full workbench experience plus governance evidence panels:

• Overview, validation metrics, and active configuration summary.

• Representation audit across original features, HUG patterns, augmented pairs, and survivor-led pattern metadata.

• Adaptive-binning evidence, including selected bin counts and information-gain summaries where available.

• Augmented-pair traceability for product, absolute-difference, sum, and signed-difference features used by the downstream estimator.

• Interaction-relaxed mining evidence, including survivor-source counts, best partners, and survivor-led pattern flags where available.

• Feature-family review across original, pattern, augmented, RPTE tree-leaf, and RPTE direct-term representations.

• RPTE governance views for backend choice, accepted tree paths, direct source terms, coefficients, support, provenance, complexity, and instance inspection.

• Pattern inventory, coefficient review, support coverage, and population-coverage summaries.

• Case-level prediction review with active pattern evidence.

• Missingness, drift, monitoring report parsing, and fairness-oriented checks.

• Configuration comparison, representation pruning analysis, and governance summary downloads.

Data inputs

The dashboard supports demo data and uploaded tabular files including CSV, TSV, Excel, and Parquet. Users can select target, identifier, protected, date, numeric, categorical, and excluded columns before fitting and reviewing a model.

Binary feature handling

Numeric columns with exactly two observed values are treated as categorical indicators during HUGIML preparation. In the dashboard this keeps binary flags, yes/no fields, and encoded indicators visible as discrete evidence rather than interval-binned numeric features.

Installed command behavior

The hugiml-dashboard console script points to hugiml.dashboard.launcher:main. It starts the Dash interface by default and selects the Streamlit interface when --ui light is supplied or HUGIML_UI=light is set.

Dashboard API modules

The following modules back the dashboard and are included in the Sphinx build so Read the Docs regenerates the complete dashboard reference from the source tree.

Streamlit app for HUGIML Governance Studio.

Run directly:

python -m streamlit run src/hugiml/dashboard/app.py

Model training/scoring helpers for the dashboard.

class hugiml.dashboard.runner.SimpleTuneResult(best_estimator_: 'Any | None', best_params_: 'dict', best_score_: 'float | None', results_: 'list[dict]', cv_splits_: 'list | None' = None, fast_path_used_: 'bool' = False, status_: 'str' = 'ok', error_: 'str | None' = None)

Parameters:

• best_estimator_ (Any | None)

• best_params_ (dict)

• best_score_ (float | None)

• results_ (list[dict])

• cv_splits_ (list | None)

• fast_path_used_ (bool)

• status_ (str)

• error_ (str | None)

class hugiml.dashboard.runner.PrunedRepresentationResult(label: 'str', estimator: 'Any', score: 'float | None', rows: 'list[dict]', kept_columns: 'list[str]', removed_columns: 'list[str]', family: 'str')

Parameters:

• label (str)

• estimator (Any)

• score (float | None)

• rows (list[dict])

• kept_columns (list[str])

• removed_columns (list[str])

• family (str)

hugiml.dashboard.runner.fit_hugiml_config(X, y, params=None, cv=5, scoring='roc_auc', random_state=2026, *, raise_on_error=False)

Fit one explicit HUGIML configuration and return a tune-like result.

Candidate configurations can legitimately mine zero patterns for a given dataset/G/L/topK combination. In that case HUGIML may raise “patterns list is empty — nothing to build”. The dashboard should display that as a failed candidate run, not crash.

Parameters:

• X (DataFrame)

• params (dict | None)

• cv (int)

• scoring (str)

• random_state (int)

• raise_on_error (bool)

hugiml.dashboard.runner.fit_feature_pruned_hugiml(X, y, base_model=None, remove_features=None, params=None, cv=5, scoring='roc_auc', random_state=2026)

Remove selected original input features, rerun HUGIML, and return result + pruned frame.

Parameters:

• X (DataFrame)

• base_model (Any | None)

• remove_features (list[str] | None)

• params (dict | None)

• cv (int)

• scoring (str)

• random_state (int)

hugiml.dashboard.runner.fit_representation_pruned_downstream(base_model, X, y, remove_columns, family, cv=5, scoring='roc_auc', random_state=2026)

Remove selected direct LR representation columns for non-RPTE models.

RPTE models containing leaf indicators are rejected because a plain LR refit on the HUGIML source matrix would discard the fitted leaf block. The RPTE final LR may also contain direct source terms, but those terms cannot be isolated with this generic source-matrix refit.

Parameters:

• base_model (Any)

• X (DataFrame)

• remove_columns (list[str])

• family (str)

• cv (int)

• scoring (str)

• random_state (int)

Return type:

tuple[PrunedRepresentationResult, DataFrame]

Experiment Workbench UI for HUGIML Studio.

The workbench is intentionally separated from Governance. It is the place to configure HUGIML and optional comparison models, run evaluations, compare metrics/plots, and promote a fitted HUGIML run into the governance workspace.

class hugiml.dashboard.workbench.ModelSpec(name: 'str', category: 'str', description: 'str', optional_dependency: 'str | None' = None)

Parameters:

• name (str)

• category (str)

• description (str)

• optional_dependency (str | None)

class hugiml.dashboard.workbench.RuleFitClassifierAdapter(tree_size=4, max_rules=100, random_state=2026)

RuleFit classifier adapter with explicit implementation labelling.

Preferred backend: imodels.RuleFitClassifier. Compatibility backend: legacy standalone rulefit.RuleFit when present. Fallback backend: sklearn-generated tree-leaf rules + logistic regression.

The fallback is intentionally labelled as “RuleFit-style fallback” in the UI so users do not confuse it with the official imodels implementation.

Parameters:

• tree_size (int)

• max_rules (int)

• random_state (int)

Display helpers for Streamlit dashboard tables.

hugiml.dashboard.display.dataframe_for_display(df, stringify_mixed_object=True)

Return a Streamlit/Arrow-safe dataframe for display.

Streamlit serializes dataframes through Arrow. Object columns that contain mixed Python types, such as integers/floats plus strings like original_plus_patterns, can trigger ArrowInvalid because Arrow attempts to coerce the column to a numeric type. Audit/config tables often have this shape by design.

This helper preserves numeric columns when they are truly numeric, and stringifies only object columns that contain mixed Python scalar types. Cells containing numpy arrays are safely converted to their list repr so that pd.isna() is never called on a multi-element array (which raises ValueError).

Parameters:

• df (Any)

• stringify_mixed_object (bool)

Return type:

DataFrame

HUGIML Governance Studio Dash interface.

The application keeps workspace selection and page navigation in a pinned header. Workbench provides equal Setup and Results views. Dataset selection, uploads, column roles, training controls, and experiment configuration live only in Setup. Governance exposes its audit pages through the same pinned navigation region.

RPTE representation and governance helpers.

The fitted HUGIML/RPTE pipeline has distinct stages: raw inputs -> HUGIML source columns -> RPTE tree splits and leaf indicators -> final LR terms. In the current representation, source columns used by accepted RPTE splits are represented through leaf indicators, while source columns not used by any accepted split are carried directly into the final LR.

hugiml.dashboard.components.rpte_governance.rpte_is_active(model)

Return True when the fitted model exposes an RPTE representation.

Parameters:

model (Any)

Return type:

bool

hugiml.dashboard.components.rpte_governance.rpte_has_tree_representation(model)

Return True when fitted RPTE leaf indicators are part of final LR.

Parameters:

model (Any)

Return type:

bool

hugiml.dashboard.components.rpte_governance.rpte_source_feature_names(model)

Names of HUGIML source columns supplied to the RPTE estimator.

Parameters:

model (Any)

Return type:

list[str]

hugiml.dashboard.components.rpte_governance.rpte_direct_source_terms_frame(model, include_zero=True)

Direct final-LR source terms not selected in accepted RPTE splits.

Fitted estimator attributes retain zero-coefficient terms; unified explanation rows provide structured metadata for non-zero terms.

Parameters:

• model (Any)

• include_zero (bool)

Return type:

DataFrame

hugiml.dashboard.components.rpte_governance.rpte_split_usage_frame(model)

Summarise source and RPTE-synthesized columns used in accepted splits.

Parameters:

model (Any)

Return type:

DataFrame

hugiml.dashboard.components.rpte_governance.rpte_source_inventory_frame(model)

Inventory every HUGIML source column and its fitted RPTE role.

Parameters:

model (Any)

Return type:

DataFrame

hugiml.dashboard.components.rpte_governance.rpte_raw_input_lineage_frame(model, X=None)

Trace raw inputs into tree-based and direct final-LR terms.

Parameters:

• model (Any)

• X (DataFrame | None)

Return type:

DataFrame

hugiml.dashboard.components.rpte_governance.rpte_representation_flow_frame(model, X=None)

Fitted representation contract for Governance UI.

Parameters:

• model (Any)

• X (DataFrame | None)

Return type:

DataFrame

hugiml.dashboard.components.rpte_governance.rpte_model_comparison_row(label, model, score, X=None)

Separated RPTE source, leaf, and direct-term counts for comparisons.

Parameters:

• label (str)

• model (Any)

• score (float | None)

• X (DataFrame | None)

Return type:

dict[str, Any]