# devikasajith/finsentinel architecture

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

- Interactive diagram: https://gitdiagram.com/devikasajith/finsentinel
- Repository: https://github.com/devikasajith/finsentinel

## Overview

FinSentinel’s main workflow turns expert-labeled Financial Phrasebank data into instruction-formatted examples, fine-tunes Phi-2 with QLoRA, then uses the saved adapter to analyze a headline in a local Gradio demo. A separate evaluation script compares base and fine-tuned outputs and saves benchmark results. Training and evaluation wiring is documented and represented by their scripts; the dataset preparation, training, evaluation, and demo implementations were sampled.

Main entry points: [`app/app.py`](https://github.com/devikasajith/finsentinel/blob/main/app/app.py) (Sentiment Analysis), [`eval/evaluate.py`](https://github.com/devikasajith/finsentinel/blob/main/eval/evaluate.py) (Base-vs-Tuned Evaluation), [`train/finetune.py`](https://github.com/devikasajith/finsentinel/blob/main/train/finetune.py) (QLoRA Fine-Tuning), [`results/phi2-finsentinel`](https://github.com/devikasajith/finsentinel/tree/main/results/phi2-finsentinel) (LoRA Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_training["Data & Training"]
  node_dataset_prep["Dataset Formatter<br/>[prepare_dataset.py]"]
  node_training_data["Train / Validation Data"]
  node_finetune["QLoRA Fine-Tuning<br/>[finetune.py]"]
end

subgraph group_model_artifacts["Model Artifacts"]
  node_phi2["Phi-2 Base Model"]
  node_adapter["LoRA Adapter"]
end

subgraph group_inference["Inference Demo"]
  node_demo["Gradio Demo<br/>[app.py]"]
  node_analysis["Sentiment Analysis<br/>[app.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Base-vs-Tuned Evaluation<br/>[evaluate.py]"]
  node_eval_results["Evaluation Results<br/>[eval_results.json]"]
end

node_analyst(("Headline User"))
node_phrasebank[("Financial Phrasebank")]

node_phrasebank -->|"provides labels"| node_dataset_prep
node_dataset_prep -->|"writes splits"| node_training_data
node_training_data -->|"loads samples"| node_finetune
node_finetune -->|"loads base"| node_phi2
node_finetune -->|"saves adapter"| node_adapter
node_analyst -->|"submits headline"| node_demo
node_demo -->|"invokes"| node_analysis
node_analysis -->|"generates with"| node_phi2
node_analysis -->|"loads adapter"| node_adapter
node_analysis -->|"returns analysis"| node_demo
node_demo -->|"shows results"| node_analyst
node_evaluation -->|"loads base"| node_phi2
node_evaluation -->|"loads adapter"| node_adapter
node_evaluation -->|"writes benchmark"| node_eval_results

click node_dataset_prep "https://github.com/devikasajith/finsentinel/blob/main/data/prepare_dataset.py"
click node_training_data "https://github.com/devikasajith/finsentinel/tree/main/data"
click node_finetune "https://github.com/devikasajith/finsentinel/blob/main/train/finetune.py"
click node_adapter "https://github.com/devikasajith/finsentinel/tree/main/results/phi2-finsentinel"
click node_demo "https://github.com/devikasajith/finsentinel/blob/main/app/app.py"
click node_analysis "https://github.com/devikasajith/finsentinel/blob/main/app/app.py"
click node_evaluation "https://github.com/devikasajith/finsentinel/blob/main/eval/evaluate.py"
click node_eval_results "https://github.com/devikasajith/finsentinel/blob/main/results/eval_results.json"

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_dataset_prep,node_training_data,node_finetune,node_analyst toneBlue
class node_phi2,node_adapter,node_phrasebank toneAmber
class node_demo,node_analysis toneMint
class node_evaluation,node_eval_results toneRose
```

## Components

### Data & Training

- [Dataset Formatter](https://github.com/devikasajith/finsentinel/blob/main/data/prepare_dataset.py): `data/prepare_dataset.py`
- [Train / Validation Data](https://github.com/devikasajith/finsentinel/tree/main/data): `data`
- [QLoRA Fine-Tuning](https://github.com/devikasajith/finsentinel/blob/main/train/finetune.py): `train/finetune.py`

### Model Artifacts

- **Phi-2 Base Model**
- [LoRA Adapter](https://github.com/devikasajith/finsentinel/tree/main/results/phi2-finsentinel): `results/phi2-finsentinel`

### Inference Demo

- [Gradio Demo](https://github.com/devikasajith/finsentinel/blob/main/app/app.py): `app/app.py`
- [Sentiment Analysis](https://github.com/devikasajith/finsentinel/blob/main/app/app.py): `app/app.py`

### Evaluation

- [Base-vs-Tuned Evaluation](https://github.com/devikasajith/finsentinel/blob/main/eval/evaluate.py): `eval/evaluate.py`
- [Evaluation Results](https://github.com/devikasajith/finsentinel/blob/main/results/eval_results.json): `results/eval_results.json`

### Other components

- **Headline User**
- **Financial Phrasebank**

## Connections

- Financial Phrasebank → Dataset Formatter: provides labels
- Dataset Formatter → Train / Validation Data: writes splits
- Train / Validation Data → QLoRA Fine-Tuning: loads samples
- QLoRA Fine-Tuning → Phi-2 Base Model: loads base
- QLoRA Fine-Tuning → LoRA Adapter: saves adapter
- Headline User → Gradio Demo: submits headline
- Gradio Demo → Sentiment Analysis: invokes
- Sentiment Analysis → Phi-2 Base Model: generates with
- Sentiment Analysis → LoRA Adapter: loads adapter
- Sentiment Analysis → Gradio Demo: returns analysis
- Gradio Demo → Headline User: shows results
- Base-vs-Tuned Evaluation → Phi-2 Base Model: loads base
- Base-vs-Tuned Evaluation → LoRA Adapter: loads adapter
- Base-vs-Tuned Evaluation → Evaluation Results: writes benchmark