AutoClassify: Intelligent Customer Remarks Categorization Pipeline

An end-to-end NLP and machine learning pipeline designed to automatically clean, vectorize, and categorize unstructured customer feedback and utility complaint remarks (e.g., power outages, billing disputes, and meter faults).

The pipeline combines deterministic rule-based temporal parsing, dense transformer embeddings, GPU-accelerated unsupervised clustering, supervised multi-class classification, and automated semantic column deduplication powered by the Google Gemini API.

---

Table of Contents

1. Architecture Overview
2. Key Features
3. Repository Structure
4. Tech Stack & Dependencies
5. Pipeline Workflow
   • Phase 1: Preprocessing & Rule-Based Temporal Categorization
   • Phase 2: Language Filtering
   • Phase 3: GPU Unsupervised Clustering & LLM Naming
   • Phase 4: Semantic Column Deduplication (Gemini API)
   • Phase 5: Supervised Classification with Feature Fusion
   • Phase 6: Uncategorized ('Others') Reallocation & Category Discovery
6. Setup & Installation
7. Input & Output Schema
8. Serialized Artifacts
9. Future Roadmap

---

Architecture Overview

Raw Customer Remarks (.xlsx)
        │
        ▼
┌──────────────────────────────────────────────┐
│ Text Standardization & Regex Outage Parsing   │ ──► [Time Categories: <4h, 4-12h, 12-24h, >24h]
└──────────────────────┬───────────────────────┘
                       │ Non-Time Remarks
                       ▼
┌──────────────────────────────────────────────┐
│ Language Segregation (langdetect)            │ ──► [Other Language Remarks]
└──────────────────────┬───────────────────────┘
                       │ English Remarks
                       ▼
┌──────────────────────────────────────────────┐
│ SentenceTransformers (all-MiniLM-L6-v2)     │ ──► 384-dimensional dense semantic vectors
└──────────────────────┬───────────────────────┘
                       │
       ┌───────────────┴────────────────────────┐
       ▼                                        ▼
[Unsupervised Branch]                   [Supervised Branch]
cuML GPU K-Means Clustering             Feature Fusion (Embeddings + Scaled Temporal Data)
       │                                        │
TF-IDF Top Keywords Extraction          Multi-Class Logistic Regression Classifier
       │                                        │
Gemini 2.5 Naming & Semantic Merge      Predicts 9 Operational Outage / Billing Categories
       ▼                                        ▼
Compact Wide-Format Output (.xlsx)      Serialized Models (.pkl) & Production Predictions

---

Key Features

• Multi-Modal Feature Fusion: Combines 384-dimensional dense semantic representations from sentence-transformers/all-MiniLM-L6-v2 with scaled temporal features (extracted duration hours and AM/PM indicators) to provide context-aware predictions.
• GPU Acceleration via RAPIDS cuML: Offloads K-Means clustering and DataFrame operations directly to NVIDIA CUDA GPUs (cudf, cuml), enabling fast processing over large remark batches.
• Automated Domain Naming via LLM: Uses Google Gemini (gemini-2.5-flash / gemini-2.5-pro) to inspect cluster keywords and representative feedback, generating concise, professional 4–7 word incident categories.
• Semantic Matrix Consolidation: Automatically identifies synonym category columns through pairwise LLM reasoning, consolidating redundant categories down to a clean operational target.
• Fallback Reallocation Engine: Employs TF-IDF, TruncatedSVD dimensionality reduction (100 components), and cosine similarity matching (0.6 threshold) to reallocate unassigned "Others" remarks or discover emerging issue clusters.

---

Repository Structure

├── Book1.xlsx                   # Labeled ground truth data for supervised model training
├── TextClassification.ipynb     # Complete development notebook (Unsupervised, Supervised, Reallocation)
├── requirement.txt              # Environment dependencies and frozen package versions
└── README.md                    # Project documentation

---

Tech Stack & Dependencies

• Language: Python 3.10+
• Deep Learning / NLP: sentence-transformers, transformers, torch, spacy, nltk
• Machine Learning: scikit-learn (LogisticRegression, StandardScaler, TfidfVectorizer, TruncatedSVD)
• GPU Acceleration: RAPIDS cudf, cuml (CUDA-enabled)
• Generative AI: Google google-generativeai (Gemini API)
• Data Manipulation & Parallelism: pandas, numpy, openpyxl, joblib, langdetect

---

Pipeline Workflow

Phase 1: Preprocessing & Rule-Based Temporal Categorization

1. Cleaning: Strips non-alphanumeric noise, normalizes excessive whitespace, and standardizes casing.
2. Regex Duration Extraction: Parses hour and day patterns (r'(\d+\.?\d*)\s*(?:hr|hrs|hour|hours|h)') directly into numerical values.
3. Deterministic Bucketing: Remarks with explicit outage durations are directly assigned to time buckets:
   • Less than 4 hours
   • More than 4 hours
   • More than 12 hours
   • More than 24 hours

Phase 2: Language Filtering

Remarks without temporal indicators are processed via langdetect parallelized across CPU workers with joblib. Non-English feedback is segregated into an Other Language Remarks column to prevent vocabulary contamination during clustering.

Phase 3: GPU Unsupervised Clustering & LLM Naming

1. Encoding: English non-time feedback is converted into 384-dim embeddings via all-MiniLM-L6-v2 in batches of 500.
2. Clustering: Embeddings are passed to cuml.cluster.KMeans on the GPU to compute cluster centroids.
3. Keyword Extraction: Identifies top unigram, bigram, and trigram terms using TfidfVectorizer (min_df=5, max_features=1000).
4. Naming: Representative samples and keywords are sent to Gemini to produce domain-specific names (e.g., Transformer Damage Causing Outages, Failed Pole Incident Category).

Phase 4: Semantic Column Deduplication (Gemini API)

When unsupervised clustering yields excessive columns (target threshold > 4 non-time columns):

• Pairwise prompt evaluations ask Gemini if two generated category titles convey identical operational semantics.
• If verified as synonyms, source columns are merged into target columns using non-destructive pandas .fillna(), reducing fragmentation.

Phase 5: Supervised Classification with Feature Fusion

1. Dataset Transformation: Formats wide labeled data (Book1.xlsx) into standard (text, label) pairs across domain categories.
2. Feature Fusion Matrix: $$\mathbf{X}{\text{combined}} = [\mathbf{E}{384} \parallel \mathbf{F}_{\text{scaled}}]$$
   • $\mathbf{E}_{384}$: 384-dimensional dense semantic sentence embedding.
   • $\mathbf{F}_{\text{scaled}}$: Standardized numeric features (extracted_hours, is_am_pm_mentioned).
3. Classifier Training: Fits a multi-class LogisticRegression classifier with balanced class weights to compensate for imbalanced remark distributions.
4. Evaluation: Evaluated against an 80/20 stratified test split, tracking precision, recall, and overall F1/accuracy scores.

Phase 6: Uncategorized ('Others') Reallocation & Category Discovery

For leftover or unclassified remarks in production:

• Cosine Match: Encodes samples using a TF-IDF + TruncatedSVD pipeline and assigns them to existing category centroids if cosine similarity exceeds 0.60.
• Emergent Topic Discovery: If remaining unclassified remarks contain $\ge 3$ similar complaints, K-Means groups them and Gemini suggests a newly emerging operational category name.

---

Setup & Installation

Prerequisites

• Python 3.10+
• Google Colab with an A100/T4 GPU runtime (recommended for cuml and sentence-transformers)
• Google Gemini API key

Installation Steps

1. Clone the repository:

   git clone https://github.com/Anshr23/AutoClassify.git
   cd AutoClassify

2. Install dependencies:

   pip install -r requirement.txt
   pip install langdetect sentence-transformers transformers

3. Set your Gemini API Key:

   • On Google Colab, store it under Secrets as GOOGLE_API_KEY.
   • In a terminal:

     export GOOGLE_API_KEY="your-gemini-api-key"

---

Input & Output Schema

Input Formats

• Training Data (Book1.xlsx): Multi-column Excel sheet where each column header represents an established operational category populated with historical remarks.
• Inference Data (Supply.xlsx, Bill.xlsx, Meter.xlsx): Raw customer logs containing at minimum a REMARKS column, with optional temporal fields such as From When Issue Is Coming.

Output Format

• Compacted Wide Excel (categorized_remarks_ML_model.xlsx): Each column corresponds to a specific category (e.g., Consumer Power Supply Failures, Partial Phase Supply Failure, Less than 4 hours), with all categorized customer remarks aligned top-to-bottom without row-offset gaps.

---

Serialized Artifacts

The supervised pipeline serializes model states using joblib for zero-retraining inference:

• sentence_transformer_model.pkl: Local instance of the MiniLM embedding model.
• logistic_regression_classifier.pkl: Trained multi-class logistic regression decision boundaries.
• scaler_for_time_features.pkl: Fitted StandardScaler ensuring consistent normalization of inference duration values.

---

Future Roadmap

• Transition from static embeddings to lightweight LoRA parameter-efficient fine-tuning on domain LLMs.
• Implement an asynchronous FastAPI service endpoint for single-remark real-time scoring.
• Build a Streamlit operational dashboard for interactive file upload, visual distribution charts, and manual review overrides.