# antonisraf/nlp-tagging-consumer-complaints architecture

> Architecture diagram of the GitHub repository antonisraf/nlp-tagging-consumer-complaints, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antonisraf/nlp-tagging-consumer-complaints
- Repository: https://github.com/antonisraf/nlp-tagging-consumer-complaints

## Overview

1. **What this repo is**
   ComplaintFlow is a Python-based NLP system for CFPB student-loan complaint tagging. Its core architecture is a supervised text-classification pipeline that turns free-text complaint narratives into hierarchical labels, then routes uncertain or disputed predictions to a human review loop.

2. **Primary architectural layers**
   The repository is split into four main layers: data exploration, model preparation/training, model evaluation, and a Streamlit application. The same text-cleaning logic is intended to be reused across training and inference to avoid training-serving skew.

3. **Data boundary**
   Raw complaint data lives under `data/` as CSV files, with a cleaned NLP-ready export also present there and in `NLP_Model_training/DATA/`. The raw dataset is the source of truth for EDA and preprocessing, while the cleaned dataset is the input boundary for vectorization and model training.

4. **EDA subsystem**
   `EDA/EDA.ipynb` and `EDA/Report_EDA.md` represent the analysis stage. This is where the dataset was filtered, label distributions were examined, low-signal metadata was pruned, and the label hierarchy and quality gates were determined. The EDA outputs drive later design choices but are not part of runtime inference.

5. **Preprocessing and feature extraction**
   `NLP_Model_training/vectorizer.py` and `app/model_pipeline.py` define the text feature boundary. The pipeline applies aggressive normalization, lemmatization, token filtering, and TF-IDF vectorization. The trained vectorizer is an artifact shared between training and app inference so the same feature space is used end to end.

6. **Model training subsystem**
   Training artifacts are created in `app/train_and_save_models.py` and supported by `NLP_Model_training/utils_NLP.py`. The project uses hierarchical classification with a coarse group prediction followed by a finer sub-issue prediction. The readme indicates ensemble classifiers built from Logistic Regression and calibrated LinearSVC, with out-of-fold probabilities used to prevent leakage in the cascade.

7. **Model evaluation and experiment boundary**
   `NLP_Model_testing/hierarchical_baseline_experiment.py` and `NLP_Model_testing/model_evaluation.py` form the validation layer. The baseline script explores alternative groupings and grid search settings, while the evaluation script locks in the chosen architecture, computes metrics, and determines the confidence threshold used to send low-confidence cases to review.

8. **Application runtime**
   The `app/` package is the operational layer. `streamlit_app.py` is the entry point, `model_pipeline.py` handles inference, `complaint_generator.py` produces synthetic complaints, and `human_review_section.py` manages reviewer corrections. This layer combines model scoring, dashboard visualization, and workflow control in one UI.

9. **Human-in-the-loop workflow**
   The app is explicitly designed as a review system, not just a classifier. Predictions below the configured confidence threshold are flagged, and the review queue can also force cases into review when the top-level label is wrong. Once a human finalizes a decision, those reviewed rows are treated as corrected and the app recomputes metrics.

10. **External dependencies and operational constraints**
    The app can call Groq’s `llama-3.3-70b-versatile` model to synthesize complaint text, using few-shot examples from anonymized narratives. API usage is rate-limited per session, and the API key is provided through `.env` or entered interactively. Streamlit is the runtime UI framework, and the project is configured through `.streamlit/config.toml`.

11. **Artifacts and outputs**
    Model and preprocessing artifacts are generated rather than hand-edited, then consumed by the app at runtime. Plots and markdown reports under `plots/`, `EDA/`, `NLP_Model_training/`, `NLP_Model_testing/`, and `app/` document the pipeline and provide traceability for the architectural decisions.

12. **End-to-end data flow**
    The overall flow is: raw CFPB complaints → EDA filtering and label engineering → text cleaning and TF-IDF vectorization → hierarchical model training and threshold tuning → saved artifacts → Streamlit inference on synthetic or real text → human review for uncertain or incorrect predictions → updated results dashboard.

Main entry points: [`app/streamlit_app.py`](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/streamlit_app.py) (Streamlit app), [`EDA/EDA.ipynb`](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/EDA/EDA.ipynb) (EDA notebook), [`app/train_and_save_models.py`](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/train_and_save_models.py) (Train models), [`NLP_Model_testing/model_evaluation.py`](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/model_evaluation.py) (Model evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_data_eda["Data & EDA"]
  node_n_raw_data[("Raw complaints<br/>CSV dataset")]
  node_n_clean_data[("Cleaned data<br/>Prepared CSV")]
  node_n_eda_notebook["EDA notebook<br/>analysis notebook<br/>[EDA.ipynb]"]
  node_n_eda_report["EDA report<br/>markdown report<br/>[Report_EDA.md]"]
end

subgraph group_g_train_eval["Training & Evaluation"]
  node_n_vectorizer["Vectorizer<br/>feature transform<br/>[vectorizer.py]"]
  node_n_utils["NLP utils<br/>preprocessing helpers<br/>[utils_NLP.py]"]
  node_n_train_save["Train models<br/>training script"]
  node_n_baseline_exp["Baseline experiment<br/>experiment script"]
  node_n_eval["Model evaluation<br/>evaluation script"]
  node_n_testing_report["Testing report<br/>markdown report"]
end

subgraph group_g_app["Application Runtime"]
  node_n_model_pipeline["Model pipeline<br/>inference pipeline<br/>[model_pipeline.py]"]
  node_n_streamlit["Streamlit app<br/>UI entrypoint<br/>[streamlit_app.py]"]
  node_n_generator["Complaint generator<br/>synthetic text"]
  node_n_review["Review section<br/>human review"]
  node_n_app_report["App report<br/>markdown report<br/>[Report_app.md]"]
end

subgraph group_g_artifacts["Artifacts"]
  node_n_clean_export[("Training export<br/>clean CSV")]
  node_n_plots["Plots<br/>analysis outputs"]
  node_n_readme["Project README<br/>overview doc<br/>[README.md]"]
end

node_n_raw_data -->|"explore"| node_n_eda_notebook
node_n_eda_notebook -->|"summarize"| node_n_eda_report
node_n_eda_notebook -->|"filter/clean"| node_n_clean_data
node_n_clean_data -->|"copy"| node_n_clean_export
node_n_clean_data -->|"fit input"| node_n_vectorizer
node_n_utils -->|"normalize"| node_n_vectorizer
node_n_vectorizer -->|"features"| node_n_train_save
node_n_utils -->|"preprocess"| node_n_train_save
node_n_train_save -->|"validate"| node_n_eval
node_n_baseline_exp -->|"compare"| node_n_eval
node_n_eval -->|"record"| node_n_testing_report
node_n_eval -->|"visualize"| node_n_plots
node_n_train_save -->|"save artifacts"| node_n_model_pipeline
node_n_model_pipeline -->|"serve predictions"| node_n_streamlit
node_n_generator -->|"demo input"| node_n_streamlit
node_n_review -->|"corrections"| node_n_streamlit
node_n_streamlit -->|"route low confidence"| node_n_review
node_n_app_report -->|"document"| node_n_streamlit
node_n_readme -.->|"orient"| node_n_eda_notebook
node_n_readme -.->|"orient"| node_n_streamlit

click node_n_raw_data "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/data/student_loan_complaints.csv"
click node_n_clean_data "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/data/student_loan_nlp_clean.csv"
click node_n_eda_notebook "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/EDA/EDA.ipynb"
click node_n_eda_report "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/EDA/Report_EDA.md"
click node_n_vectorizer "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_training/vectorizer.py"
click node_n_utils "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_training/utils_NLP.py"
click node_n_train_save "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/train_and_save_models.py"
click node_n_baseline_exp "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/hierarchical_baseline_experiment.py"
click node_n_eval "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/model_evaluation.py"
click node_n_testing_report "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/Report_NLP_Model_testing.md"
click node_n_model_pipeline "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/model_pipeline.py"
click node_n_streamlit "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/streamlit_app.py"
click node_n_generator "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/complaint_generator.py"
click node_n_review "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/human_review_section.py"
click node_n_app_report "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/Report_app.md"
click node_n_clean_export "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_training/DATA/student_loan_nlp_clean.csv"
click node_n_plots "https://github.com/antonisraf/nlp-tagging-consumer-complaints/tree/main/plots"
click node_n_readme "https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_raw_data,node_n_clean_data,node_n_eda_notebook,node_n_eda_report toneBlue
class node_n_vectorizer,node_n_utils,node_n_train_save,node_n_baseline_exp,node_n_eval,node_n_testing_report toneAmber
class node_n_model_pipeline,node_n_streamlit,node_n_generator,node_n_review,node_n_app_report toneMint
class node_n_clean_export,node_n_plots,node_n_readme toneRose
```

## Components

### Data & EDA

Raw complaints, cleaned exports, and exploratory analysis that define the label schema and preprocessing choices.

- [Raw complaints](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/data/student_loan_complaints.csv): CSV dataset · Source-of-truth CFPB student-loan complaint narratives and metadata. · `data/student_loan_complaints.csv`
- [Cleaned data](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/data/student_loan_nlp_clean.csv): Prepared CSV · NLP-ready complaint dataset used as the boundary between exploration and modeling. · `data/student_loan_nlp_clean.csv`
- [EDA notebook](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/EDA/EDA.ipynb): analysis notebook · Explores labels, filters low-signal fields, and informs hierarchy and quality gates. · `EDA/EDA.ipynb`
- [EDA report](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/EDA/Report_EDA.md): markdown report · Narrative summary of exploratory findings and dataset decisions. · `EDA/Report_EDA.md`

### Training & Evaluation

Model preparation, vectorization, hierarchical training, and experiment evaluation.

- [Vectorizer](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_training/vectorizer.py): feature transform · Text normalization and TF-IDF feature extraction shared by training and inference. · `NLP_Model_training/vectorizer.py`
- [NLP utils](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_training/utils_NLP.py): preprocessing helpers · Reusable text-cleaning and NLP utility functions supporting the model pipeline. · `NLP_Model_training/utils_NLP.py`
- [Train models](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/train_and_save_models.py): training script · Builds hierarchical classifiers and persists the trained artifacts for runtime use. · `app/train_and_save_models.py`
- [Baseline experiment](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/hierarchical_baseline_experiment.py): experiment script · Explores grouping and grid-search settings for hierarchical classification. · `NLP_Model_testing/hierarchical_baseline_experiment.py`
- [Model evaluation](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/model_evaluation.py): evaluation script · Computes metrics and selects the confidence threshold for routing cases to review. · `NLP_Model_testing/model_evaluation.py`
- [Testing report](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_testing/Report_NLP_Model_testing.md): markdown report · Documented validation results and experiment conclusions. · `NLP_Model_testing/Report_NLP_Model_testing.md`

### Application Runtime

Streamlit UI, inference pipeline, synthetic complaint generation, and human review loop.

- [Model pipeline](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/model_pipeline.py): inference pipeline · Loads artifacts, preprocesses text, vectorizes input, and returns hierarchical predictions. · `app/model_pipeline.py`
- [Streamlit app](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/streamlit_app.py): UI entrypoint · Operational dashboard for scoring, review, and metrics visualization. · `app/streamlit_app.py`
- [Complaint generator](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/complaint_generator.py): synthetic text · Creates example complaints for demo and testing workflows. · `app/complaint_generator.py`
- [Review section](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/human_review_section.py): human review · Handles reviewer corrections, disputed predictions, and queue management. · `app/human_review_section.py`
- [App report](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/app/Report_app.md): markdown report · Notes about the runtime workflow and app behavior. · `app/Report_app.md`

### Artifacts

Saved models, plots, and reports consumed or produced across the pipeline.

- [Training export](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/NLP_Model_training/DATA/student_loan_nlp_clean.csv): clean CSV · Cleaned dataset copy stored with training assets for reproducible model fitting. · `NLP_Model_training/DATA/student_loan_nlp_clean.csv`
- [Plots](https://github.com/antonisraf/nlp-tagging-consumer-complaints/tree/main/plots): analysis outputs · Saved visual artifacts that document data exploration and model evaluation. · `plots`
- [Project README](https://github.com/antonisraf/nlp-tagging-consumer-complaints/blob/main/README.md): overview doc · Top-level repository description and usage guidance. · `README.md`

## Connections

- Raw complaints → EDA notebook: explore · EDA begins from raw complaint records.
- EDA notebook → EDA report: summarize · Findings are captured in the EDA report.
- EDA notebook → Cleaned data: filter/clean · Exploration drives label engineering and dataset pruning.
- Cleaned data → Training export: copy · Cleaned data is exported for training-time use.
- Cleaned data → Vectorizer: fit input · Clean text is the input boundary for feature extraction.
- NLP utils → Vectorizer: normalize · Shared NLP helpers support the feature pipeline.
- Vectorizer → Train models: features · Vectorized text feeds model training.
- NLP utils → Train models: preprocess · Training reuses the same text-cleaning logic.
- Train models → Model evaluation: validate · Trained models are evaluated and thresholded.
- Baseline experiment → Model evaluation: compare · Baseline experiments inform the final evaluation setup.
- Model evaluation → Testing report: record · Metrics and threshold decisions are documented.
- Model evaluation → Plots: visualize · Evaluation produces supporting plots.
- Train models → Model pipeline: save artifacts · Inference loads the persisted models and vectorizer.
- Model pipeline → Streamlit app: serve predictions · The UI calls the pipeline for scoring.
- Complaint generator → Streamlit app: demo input · Synthetic complaints can be generated inside the app.
- Review section → Streamlit app: corrections · Human review updates disputed or low-confidence cases.
- Streamlit app → Review section: route low confidence · Cases below threshold are sent to review.
- App report → Streamlit app: document · App behavior and workflow are described in the app report.
- Project README → EDA notebook: orient · Repository documentation contextualizes the analysis stage.
- Project README → Streamlit app: orient · Repository documentation contextualizes the runtime app.
