An omnichannel strategy development framework leveraging customer opinion divergence via large language models and explainable AI

This is the official repository of "An omnichannel strategy development framework leveraging customer opinion divergence via large language models and explainable AI".

Framework

Set up

Please follow the steps below to perform the installation：

1. Create virtual environment

conda create -n omnichannel python=3.9
conda activate omnichannel

2. Install packages

pip install -r requirements.txt

3. Configure API key

Create a .env file in the omnichannel/ directory:

OPENAI_API_KEY=your_openai_api_key_here

Note: An OpenAI API key is required for aspect normalization (Step 2) and aspect type determination (Step 8). You can obtain one at platform.openai.com.

4. Download model weights

Download model.pt from imlab-ewha/KcELECTRA-base-v2022-Aspect-Extraction and place it at: code/frequent_aspect_mining/aspect_extraction/models/model.pt

Quick Start

• main.py runs all steps end-to-end in order.
• Each step reads from and writes to the resource/ directory, so no arguments are needed.
• Final output: resource/9_scenario/scenario_assignment.csv.
• If a step fails, the pipeline stops immediately and prints which step failed.
• We provide a sample Korean review dataset for inference testing at resource/example_review.csv.

cd omnichannel/
python main.py

Scripts

Step 1 — Aspect Extraction

• code/frequent_aspect_mining/aspect_extraction/aspect_extraction.py
• Extracts product aspects from Korean reviews using a fine-tuned KcELECTRA model.

Argument	Default	Description
--input	resource/example_review.csv	Input review CSV
--output	resource/1_aspect_extraction/	Output directory
--batch-size	50	Inference batch size

Step 2 — Aspect Normalization

• code/frequent_aspect_mining/aspect_normalization/aspect_normalization.py
• Normalizes raw aspect expressions into standardized forms via the OpenAI Chat API.

Argument	Default	Description
--input	resource/1_aspect_extraction/aspect_extraction.csv	Input CSV
--output-dir	resource/2_aspect_normalization/	Output directory
--model	gpt-4o-mini	OpenAI model
--temperature	0.0	Sampling temperature
--seed	42	Random seed

Step 3 — Aspect Selection

• code/frequent_aspect_mining/aspect_selection/aspect_selection.py
• Selects the top-k most frequent normalized aspects.

Argument	Default	Description
--input	resource/2_aspect_normalization/	Normalization output dir (picks latest CSV)
--output-dir	resource/3_aspect_selection/	Output directory
--top-k	10	Number of aspects to select

Step 4 — Sentiment Analysis

• code/aspect_contribution_pairs_mining/overall_satisfaction_score_combination/sentiment_analysis.py
• Classifies each review as positive / negative using a GRU model.

Argument	Default	Description
--input	resource/example_review.csv	Input review CSV
--output-dir	resource/4_sentiment_analysis/	Output directory

Step 5 — Overall Satisfaction Score Combination

• code/aspect_contribution_pairs_mining/overall_satisfaction_score_combination/overall_satisfaction_score_combination.py
• Combines rating and sentiment probability into an overall satisfaction score.

Argument	Default	Description
--input	resource/4_sentiment_analysis/sentiment_analysis.csv	Input CSV
--output-dir	resource/5_overall_satisfaction/	Output directory

Step 6 — Aspect Contribution Calculation (Random Forest)

• code/aspect_contribution_pairs_mining/aspect_contribution_calculation/model_training.py
• Trains a Random Forest regressor per channel (online / offline) to predict overall satisfaction from binary aspect-presence features.

Argument	Default	Description
--satisfaction	resource/5_overall_satisfaction/overall_satisfaction.csv	Overall satisfaction scores
--top-aspects	resource/3_aspect_selection/top_aspects.csv	Top-k aspects list
--reviews	resource/3_aspect_selection/top_aspect_reviews.csv	Aspect-review pairs
--output-dir	resource/6_aspect_contribution/	Output directory

Step 7 — Aspect Contribution Calculation (SHAP Analysis)

• code/aspect_contribution_pairs_mining/aspect_contribution_calculation/aspect_contribution_calculation.py
• Computes SHAP values from trained RF models and outputs per-aspect mean SHAP per channel.

Argument	Default	Description
--model-dir	resource/6_aspect_contribution/models/	Directory with {channel}_rf.pkl files
--output-dir	resource/7_shap/	Output directory

Output columns: aspect, online_mean_abs_shap, online_mean_shap, offline_mean_abs_shap, offline_mean_shap

Step 8 — Aspect Type Determination

• code/strategy_development/aspect_type_determination/aspect_type_determination.py
• Classifies each aspect as search (evaluable before purchase) or experience (evaluable only after use) via the OpenAI Chat API.

Argument	Default	Description
--aspects	resource/3_aspect_selection/top_aspects.csv	Top-k aspects list
--output	resource/8_aspect_type/aspect_types.csv	Output CSV
--model	gpt-4o-mini	OpenAI model
--temperature	0.0	Sampling temperature
--seed	42	Random seed

Step 9 — Scenario Assignment

• code/strategy_development/aspect_scenario_assignment/aspect_scenario_assignment.py
• Assigns an omnichannel strategy scenario (S1–S4) to each aspect.

Scenario	Type	Dominant Channel
S1	Search	Online
S2	Search	Offline
S3	Experience	Online
S4	Experience	Offline

Argument	Default	Description
--shap	resource/7_shap/shap.csv	SHAP results
--types	resource/8_aspect_type/aspect_types.csv	Aspect type results
--output-dir	resource/9_scenario/	Output directory
--epsilon	0.0	Min |online − offline| SHAP difference to assign a scenario