# sahilnegi4444/higs_gat_based_summarization architecture

> Architecture diagram of the GitHub repository sahilnegi4444/higs_gat_based_summarization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sahilnegi4444/higs_gat_based_summarization
- Repository: https://github.com/sahilnegi4444/higs_gat_based_summarization

## Overview

1. This repository is an offline research/training pipeline for multi-document abstractive summarization of Indian English news. The main boundary is between experiment code under `scripts/` and model implementations under `models/`, with configuration-driven runs from `configs/`.

2. The central system is HiGS, a dual-encoder fusion summarizer implemented in `models/higs_model.py`. Its data path is: multiple related articles in → sentence splitting and tokenization → BERT sentence embeddings for structural modeling → adjacency matrix construction from similarity/entity overlap → GAT layers → projection to BART’s latent size → fusion with BART’s native encoder output → BART decoder generates the summary.

3. HiGS has an explicit structural vs. semantic split. Pathway A captures cross-document relations with BERT + graph attention; Pathway B preserves fluent generation with a frozen BART encoder/decoder backbone. The architecture relies on dual tokenization because BERT and BART do not share vocabularies or embedding spaces.

4. Training is staged and intentionally decoupled. `scripts/train_higs.py` runs phase 1 to train the graph-side components while keeping BART frozen, then phase 2 to unfreeze the decoder and align generation to the learned graph representations. This two-phase boundary is important to preserve pretrained language ability while adding factual grounding.

5. Baseline models are handled separately from HiGS. `models/baselines.py` and `scripts/train_baselines.py` cover encoder-decoder baselines such as PRIMERA, LED, LongT5, and Flan-T5-XL, while `models/llm_lora.py` covers large-model fine-tuning via LoRA/QLoRA for models like Mistral, Llama 3, Qwen2, and Gemma. The repo therefore compares from-scratch summarizers against parameter-efficient LLM adaptation.

6. Data preparation is centralized in `scripts/prepare_data.py`. The README indicates a clean → split → stats flow: strip HTML and deduplicate raw data, build train/validation/test splits, then compute dataset statistics and EDA plots. The cleaned dataset is expected externally in `data/newssumm_cleaned.parquet`, so raw data is a separate input boundary from the codebase.

7. Evaluation is split into two layers. `scripts/evaluate_higs.py` measures generation quality and runtime characteristics such as ROUGE, BERTScore, latency, throughput, and peak VRAM. `scripts/run_local_consistency_check.py` adds factuality checks using entity overlap, a DeBERTa-based NLI pass, and topic overlap, making factual consistency a distinct subsystem from lexical quality.

8. Inference/qualitative generation is isolated in `scripts/generate_mds.py`. It is meant to synthesize a summary from multiple articles directly, separate from training and batch evaluation. This gives the repo a clear “demo/inference” entry point apart from experiment execution.

9. The `configs/` directory is the experiment control plane. Each YAML file maps to a specific model family or training regime, including HiGS and the baseline suites. Architecturally, this means model choice, training hyperparameters, and PEFT settings are externalized rather than hard-coded.

10. `results/` is a persisted artifact layer, not just logs. It stores benchmark JSONs, evaluation reports, factual consistency outputs, generated samples, and a summary CSV. For diagramming, treat this as the output sink for all training/evaluation workflows rather than an active runtime component.

11. Supporting assets are split across `docs/` and `notebooks/`. `docs/architecture.md` and the diagram image provide the formal mathematical/visual specification, while `notebooks/dataset_analysis.ipynb` is exploratory analysis rather than part of the production pipeline.

12. The runtime assumptions matter for the architecture: Python with PyTorch, GPU acceleration, CUDA, and spaCy for sentence splitting/named entity extraction. Those libraries primarily support the graph construction and factual consistency subsystems, especially entity-aware adjacency building and consistency analysis.

Main entry points: [`scripts/train_higs.py`](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/train_higs.py) (Train HiGS), [`scripts/train_baselines.py`](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/train_baselines.py) (Train baselines), [`models/higs_model.py`](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/higs_model.py) (HiGS model), [`scripts/evaluate_higs.py`](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/evaluate_higs.py) (Evaluate HiGS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_configs_higs["HiGS config<br/>yaml config<br/>[higs.yaml]"]
  node_configs_baselines["Baseline configs<br/>yaml config"]
end

subgraph group_models["Model layer"]
  node_higs_model["HiGS model<br/>dual-encoder summarizer<br/>[higs_model.py]"]
  node_baselines_model["Baselines<br/>[baselines.py]"]
  node_llm_lora["LLM LoRA<br/>peft finetuning<br/>[llm_lora.py]"]
end

subgraph group_scripts["Pipeline scripts"]
  node_prepare_data["Prepare data<br/>data prep<br/>[prepare_data.py]"]
  node_train_higs["Train HiGS<br/>two-phase training<br/>[train_higs.py]"]
  node_train_baselines["Train baselines<br/>baseline training<br/>[train_baselines.py]"]
  node_evaluate_higs["Evaluate HiGS<br/>generation eval<br/>[evaluate_higs.py]"]
  node_consistency_check["Consistency check<br/>factuality eval"]
  node_generate_mds["Generate summary<br/>inference<br/>[generate_mds.py]"]
end

subgraph group_artifacts["Artifacts"]
  node_benchmark_reports[("Benchmarks<br/>results")]
  node_eval_reports[("Eval reports<br/>results")]
  node_factual_report["Factual report<br/>results"]
  node_generated_samples["Samples<br/>results"]
  node_benchmark_table["Summary table<br/>results"]
end

subgraph group_reference["Reference"]
  node_architecture_doc["Architecture doc<br/>documentation<br/>[architecture.md]"]
  node_dataset_notebook["Data notebook<br/>exploration"]
end

node_configs_higs -->|"drives"| node_train_higs
node_configs_baselines -->|"drives"| node_train_baselines
node_configs_baselines -->|"selects"| node_llm_lora
node_prepare_data -->|"feeds"| node_train_higs
node_prepare_data -->|"feeds"| node_train_baselines
node_higs_model -->|"implements"| node_train_higs
node_baselines_model -->|"implements"| node_train_baselines
node_llm_lora -->|"extends"| node_train_baselines
node_train_higs -->|"evaluated by"| node_evaluate_higs
node_train_higs -->|"served by"| node_generate_mds
node_train_baselines -->|"writes"| node_benchmark_reports
node_evaluate_higs -->|"writes"| node_benchmark_reports
node_evaluate_higs -->|"writes"| node_eval_reports
node_consistency_check -->|"writes"| node_factual_report
node_generate_mds -->|"writes"| node_generated_samples
node_benchmark_reports -->|"aggregates"| node_benchmark_table
node_architecture_doc -->|"documents"| node_higs_model
node_dataset_notebook -->|"analyzes"| node_prepare_data
node_higs_model -->|"measured by"| node_evaluate_higs
node_higs_model -->|"checked by"| node_consistency_check
node_generate_mds -->|"reviewed by"| node_consistency_check

click node_configs_higs "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/configs/higs.yaml"
click node_higs_model "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/higs_model.py"
click node_baselines_model "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/baselines.py"
click node_llm_lora "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/llm_lora.py"
click node_prepare_data "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/prepare_data.py"
click node_train_higs "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/train_higs.py"
click node_train_baselines "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/train_baselines.py"
click node_evaluate_higs "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/evaluate_higs.py"
click node_consistency_check "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/run_local_consistency_check.py"
click node_generate_mds "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/generate_mds.py"
click node_benchmark_reports "https://github.com/sahilnegi4444/higs_gat_based_summarization/tree/main/results/benchmark_reports"
click node_eval_reports "https://github.com/sahilnegi4444/higs_gat_based_summarization/tree/main/results/eval_reports"
click node_factual_report "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/results/factual_consistency_report.json"
click node_generated_samples "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/results/generated_samples.json"
click node_benchmark_table "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/results/benchmark_table.csv"
click node_architecture_doc "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/docs/architecture.md"
click node_dataset_notebook "https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/notebooks/dataset_analysis.ipynb"

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_configs_higs,node_configs_baselines toneBlue
class node_higs_model,node_baselines_model,node_llm_lora toneAmber
class node_prepare_data,node_train_higs,node_train_baselines,node_evaluate_higs,node_consistency_check,node_generate_mds toneMint
class node_benchmark_reports,node_eval_reports,node_factual_report,node_generated_samples,node_benchmark_table toneRose
class node_architecture_doc,node_dataset_notebook toneIndigo
```

## Components

### Control plane

Experiment configuration and run orchestration

- [HiGS config](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/configs/higs.yaml): yaml config · Configuration for the dual-encoder HiGS training regime. · `configs/higs.yaml`
- **Baseline configs**: yaml config · Configuration files for classical encoder-decoder baselines and PEFT LLM runs.

### Model layer

Summarization model implementations

- [HiGS model](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/higs_model.py): dual-encoder summarizer · Graph-grounded abstractive summarizer combining BERT, GAT, and BART. · `models/higs_model.py`
- [Baselines](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/baselines.py): seq2seq baselines · Implementation of PRIMERA, LED, LongT5, and Flan-T5 style summarizers. · `models/baselines.py`
- [LLM LoRA](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/models/llm_lora.py): peft finetuning · Parameter-efficient fine-tuning for large models using LoRA/QLoRA. · `models/llm_lora.py`

### Pipeline scripts

Training, evaluation, data preparation, and inference entry points

- [Prepare data](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/prepare_data.py): data prep · Cleans raw news, builds splits, and computes dataset statistics. · `scripts/prepare_data.py`
- [Train HiGS](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/train_higs.py): two-phase training · Runs staged HiGS training with frozen then unfrozen BART components. · `scripts/train_higs.py`
- [Train baselines](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/train_baselines.py): baseline training · Trains the encoder-decoder baseline suite from configuration. · `scripts/train_baselines.py`
- [Evaluate HiGS](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/evaluate_higs.py): generation eval · Measures ROUGE, BERTScore, latency, throughput, and VRAM usage. · `scripts/evaluate_higs.py`
- [Consistency check](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/run_local_consistency_check.py): factuality eval · Runs entity overlap, NLI, and topic overlap checks for factual consistency. · `scripts/run_local_consistency_check.py`
- [Generate summary](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/scripts/generate_mds.py): inference · Direct multi-document summary generation entry point. · `scripts/generate_mds.py`

### Artifacts

Persisted outputs and reports

- [Benchmarks](https://github.com/sahilnegi4444/higs_gat_based_summarization/tree/main/results/benchmark_reports): results · Stored benchmark JSON reports for model comparisons. · `results/benchmark_reports`
- [Eval reports](https://github.com/sahilnegi4444/higs_gat_based_summarization/tree/main/results/eval_reports): results · Stored evaluation outputs for model runs. · `results/eval_reports`
- [Factual report](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/results/factual_consistency_report.json): results · Persisted factual consistency analysis output. · `results/factual_consistency_report.json`
- [Samples](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/results/generated_samples.json): results · Persisted generated summaries and example outputs. · `results/generated_samples.json`
- [Summary table](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/results/benchmark_table.csv): results · Aggregated benchmark comparison CSV. · `results/benchmark_table.csv`

### Reference

Documentation and exploratory analysis

- [Architecture doc](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/docs/architecture.md): documentation · Formal description of the HiGS design and math. · `docs/architecture.md`
- [Data notebook](https://github.com/sahilnegi4444/higs_gat_based_summarization/blob/main/notebooks/dataset_analysis.ipynb): exploration · Exploratory dataset analysis notebook. · `notebooks/dataset_analysis.ipynb`

## Connections

- HiGS config → Train HiGS: drives · HiGS configuration selects training regime and hyperparameters.
- Baseline configs → Train baselines: drives · Baseline and PEFT configuration files control experiment runs.
- Baseline configs → LLM LoRA: selects · Configuration options map to PEFT LLM fine-tuning setups.
- Prepare data → Train HiGS: feeds · Prepared splits provide training and validation inputs for HiGS.
- Prepare data → Train baselines: feeds · Prepared splits are reused by baseline training runs.
- HiGS model → Train HiGS: implements · HiGS model is the core architecture trained in the staged pipeline.
- Baselines → Train baselines: implements · Baseline model implementations are exercised by the baseline trainer.
- LLM LoRA → Train baselines: extends · PEFT LLM adaptation is part of the comparison training suite.
- Train HiGS → Evaluate HiGS: evaluated by · Trained HiGS checkpoints are scored by the evaluation script.
- Train HiGS → Generate summary: served by · HiGS checkpoints can be used for qualitative summary generation.
- Train baselines → Benchmarks: writes · Baseline runs emit benchmark JSON artifacts.
- Evaluate HiGS → Benchmarks: writes · Generation evaluation produces benchmark reports.
- Evaluate HiGS → Eval reports: writes · Per-run evaluation outputs are stored as JSON reports.
- Consistency check → Factual report: writes · Factual consistency analysis is persisted as a dedicated report.
- Generate summary → Samples: writes · Inference produces generated summary samples for inspection.
- Benchmarks → Summary table: aggregates · Benchmark reports are summarized into a comparison table.
- Architecture doc → HiGS model: documents · Documentation describes the HiGS architecture and data flow.
- Data notebook → Prepare data: analyzes · Notebook supports exploratory analysis of the dataset preparation workflow.
- HiGS model → Evaluate HiGS: measured by · HiGS outputs are assessed on quality and runtime metrics.
- HiGS model → Consistency check: checked by · HiGS generations can be inspected for factual consistency.
- Generate summary → Consistency check: reviewed by · Generated summaries can be passed to factual consistency checks.
