# prosusai/finbert architecture

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

- Interactive diagram: https://gitdiagram.com/prosusai/finbert
- Repository: https://github.com/prosusai/finbert

## Overview

##### Project Type and Purpose
- This is a Python‐based machine‐learning pipeline for financial‐domain sentiment analysis.
- It consists of two main workflows:
– Offline training (notebook, dataset scripts)
– Runtime inference (CLI/predict script)
- Core functionality is provided by the `finbert` Python package, which wraps Hugging Face’s BERT model for classification.

##### File Structure
Top-level artifacts and their roles:
- environment.yml, Dockerfile → Deployment/configuration (Conda env, container)
- config.json → Model/config parameters for `.from_pretrained(...)`
- finbert/finbert.py, finbert/utils.py → Core library: model loading, tokenization, inference APIs
- notebooks/finbert_training.ipynb → Training pipeline (data → model)
- scripts/datasets.py → Data ingestion & splitting (build train/val/test CSVs)
- scripts/predict.py → CLI for batch‐mode inference producing CSV outputs
- main.py → (Optional) Top‐level entry point (could orchestrate tasks)
- examples.csv, test.txt → Sample inputs/outputs

##### Extract Architectural Insights from the README
- Two model types:
– Language model fine‐tuning on TRC2
– Sentiment classifier on Financial PhraseBank
- Training parameters (epochs, batch size, learning rate, unfreeze technique)
- Models are stored on disk under `models/...` with accompanying `config.json`
- Inference script loads model via `.from_pretrained()` from local directory

1. Data Sources
– External datasets (Reuters TRC2 [offline], FinancialPhraseBank)
– Raw text files (`test.txt`, user-provided)
2. Data Preparation
– `scripts/datasets.py`
– Outputs: `data/sentiment_data/{train.csv,validation.csv,test.csv}`
3. Training Pipeline
– `notebooks/finbert_training.ipynb` (calls FinBERT API, PyTorch training loop)
– Produces model artifacts under `models/classifier_model/finbert-sentiment`
4. Model Registry/Storage
– Local filesystem (`models/...`) or Hugging Face model hub
5. Core Library
– `finbert` package:
- ModelLoader (loads BERT via `pytorch_pretrained_bert`)
- Tokenizer, inference code, utilities
6. Inference/Serving
– `scripts/predict.py` (CLI)
– Possibly `main.py` if used as entrypoint/CLI wrapper
– Outputs: CSV with sentences + softmax probabilities + sentiment score
7. Deployment/Environment
– Conda environment (`environment.yml`)
– Docker container (`Dockerfile`, `.dockerignore`)

- Raw Dataset → Data Preparation Script → Prepared CSV files
- Prepared CSV → Training Notebook → Model Artifacts
- Model Artifacts + config.json → Core Library (`.from_pretrained`)
- Core Library + Input Text → Inference Script → Output CSV
- Dockerfile & environment.yml → Provision runtime/training environment

c. Architectural Patterns and Principles
- Pipeline pattern: clear separation between data ingestion, training, inference
- Modular design: core logic in `finbert` package, scripts as thin wrappers
- Configuration‐driven: parameters in config.json and notebook variables
- Reproducibility: Docker + Conda environment

d. Key Technologies & Frameworks
- Python 3.x, Conda
- PyTorch via `pytorch_pretrained_bert` (soon `transformers`)
- Hugging Face model hub (external storage)
- Jupyter Notebook for interactive training
- CLI scripts for batch workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Datasets
    subgraph "Data & Datasets"
        Raw1["Reuters TRC2 Dataset"]:::external
        Raw2["FinancialPhraseBank"]:::external
        UserInput["Raw Text (test.txt)"]:::data
        click UserInput "https://github.com/prosusai/finbert/blob/master/test.txt"
    end

    %% Data Preparation
    subgraph "Data Preparation"
        DatasetBuilder["Dataset Builder\n(scripts/datasets.py)"]:::data
        click DatasetBuilder "https://github.com/prosusai/finbert/blob/master/scripts/datasets.py"
        CSVStorage["Prepared CSVs\n(data/sentiment_data/)"]:::storage
    end

    %% Training Workflow
    subgraph "Training Workflow"
        Notebook["Training Notebook\n(notebooks/finbert_training.ipynb)"]:::training
        click Notebook "https://github.com/prosusai/finbert/blob/master/notebooks/finbert_training.ipynb"
    end

    %% Model Storage
    subgraph "Model Storage"
        ModelArtifacts["Model Artifacts\n(models/.../)"]:::storage
    end

    %% Core Library
    subgraph "Core Library"
        FinBERTInit["__init__.py"]:::core
        click FinBERTInit "https://github.com/prosusai/finbert/blob/master/finbert/__init__.py"
        FinBERTCore["finbert.py\nModelLoader & Inference"]:::core
        click FinBERTCore "https://github.com/prosusai/finbert/blob/master/finbert/finbert.py"
        Utils["utils.py"]:::core
        click Utils "https://github.com/prosusai/finbert/blob/master/finbert/utils.py"
    end

    %% Inference / Serving
    subgraph "Inference / Serving"
        PredictCLI["Predict CLI\n(scripts/predict.py)"]:::inference
        click PredictCLI "https://github.com/prosusai/finbert/blob/master/scripts/predict.py"
        MainEntry["Main Entry Point\n(main.py)"]:::inference
        click MainEntry "https://github.com/prosusai/finbert/blob/master/main.py"
        OutputCSV["Output CSV\n(examples.csv)"]:::data
        click OutputCSV "https://github.com/prosusai/finbert/blob/master/examples.csv"
    end

    %% Deployment / Configuration
    subgraph "Deployment / Configuration"
        Env["environment.yml"]:::deployment
        click Env "https://github.com/prosusai/finbert/blob/master/environment.yml"
        Dockerfile["Dockerfile"]:::deployment
        click Dockerfile "https://github.com/prosusai/finbert/tree/master/Dockerfile"
        Dockerignore[".dockerignore"]:::deployment
        click Dockerignore "https://github.com/prosusai/finbert/blob/master/.dockerignore"
        Config["config.json"]:::config
        click Config "https://github.com/prosusai/finbert/blob/master/config.json"
    end

    %% External Services
    HF["Hugging Face Model Hub"]:::external

    %% Data Flows
    Raw1 --> DatasetBuilder
    Raw2 --> DatasetBuilder
    DatasetBuilder --> CSVStorage
    CSVStorage --> Notebook
    Notebook --> ModelArtifacts
    HF -.-> ModelArtifacts

    %% Core Integration
    ModelArtifacts -->|".from_pretrained()"| FinBERTCore
    Config -->|"model params"| FinBERTCore
    FinBERTInit --> FinBERTCore
    Utils --> FinBERTCore

    %% Inference Flow
    ModelArtifacts --> PredictCLI
    FinBERTCore -->|"infer()"| PredictCLI
    UserInput --> PredictCLI
    PredictCLI --> OutputCSV
    MainEntry --> PredictCLI

    %% Deployment Links
    Env -.-> Notebook
    Env -.-> PredictCLI
    Dockerfile -.-> Notebook
    Dockerfile -.-> PredictCLI

    %% Styles
    classDef data fill:#D0E8FF,stroke:#0066CC,stroke-width:2px;
    classDef storage fill:#DFFFE0,stroke:#33AA33,stroke-width:2px,stroke-dasharray: 5 5;
    classDef core fill:#E0FFE0,stroke:#228B22,stroke-width:2px;
    classDef training fill:#FFE5CC,stroke:#FF8C00,stroke-width:2px;
    classDef inference fill:#F0E0FF,stroke:#9932CC,stroke-width:2px;
    classDef deployment fill:#F0F0F0,stroke:#666666,stroke-width:2px,stroke-dasharray: 3 3;
    classDef config fill:#FFF5CC,stroke:#CCCC33,stroke-width:2px;
    classDef external fill:#FFFFFF,stroke:#999999,stroke-width:1px,stroke-dasharray: 2 2;
```
