# andriymulyar/semantic-text-similarity architecture

> Architecture diagram of the GitHub repository andriymulyar/semantic-text-similarity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andriymulyar/semantic-text-similarity
- Repository: https://github.com/andriymulyar/semantic-text-similarity

## Overview

##### Project type and purpose
- This is an open-source Python library (“semantic-text-similarity”) that provides a clean interface over fine-tuned BERT models (and fallback string-based metrics) to compute semantic similarity scores.
- It abstracts away research benchmarking into easy “predict(…)” calls for real-world applications.

##### File structure
Top-level:
- examples/ – sample scripts showing how to call the library
- semantic_text_similarity/ – the core package
- data/ – data loaders for STS-B datasets (STS-B, MED-STS)
- models/ – model implementations
– bert/ – BERT-based similarity models and preprocessing
– string_similarity/ – lexical similarity baselines
- util and test utilities
- setup.py, README.md, cache location (~/.cache/torch/…)

##### README for additional insights
- Two main pre-trained BERT models: Web STS and Clinical STS
- Uses Huggingface pytorch-transformers under the hood
- Exposes a simple Python API: instantiate model class, call predict()

a. Main components:
1. User Layer (scripts, CLI, application code)
2. Semantic-Text-Similarity Package
- API Facade (WebBertSimilarity, ClinicalBertSimilarity, StringSimilarity)
- Data Loader (semantic_text_similarity.data)
- Preprocessing (bert_preprocessing.py)
- Model Inference (similarity.py in bert/ and lexical metrics)
- Utilities (tokenization helpers, test utilities)
3. External Dependencies
- Huggingface pytorch-transformers (model zoo, tokenizers)
- GPU/CPU device
- Local cache directory for downloaded checkpoints
b. Relationships & data flow:
1. User calls Model API →
2. API Facade invokes Data Loader (optional if batching raw text) →
3. Preprocessing transforms sentences into token IDs →
4. BERT model loaded from cache or downloaded via Huggingface →
5. Forward pass → similarity score output →
6. Return real-valued score to user
c. Architectural patterns & principles:
- Layered architecture: API layer, data layer, model layer.
- Separation of concerns: data handling vs. preprocessing vs. model inference.
- Modular design: interchangeable similarity backends (BERT vs. string metrics).
d. Key technologies/frameworks:
- Python packaging (setup.py)
- pytorch-transformers (Huggingface)
- PyTorch for model execution
- CSV data files for STS datasets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        direction TB
        U1["med_sts_clinical.py"]:::user
        U2["sts_b_web.py"]:::user
    end

    %% API Facade
    subgraph "API Facade"
        direction TB
        API1["WebBertSimilarity"]:::api
        API2["ClinicalBertSimilarity"]:::api
        API3["StringSimilarity"]:::api
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DL["DataLoader"]:::data
        STS_TRAIN["sts-train.csv"]:::data
        STS_DEV["sts-dev.csv"]:::data
        STS_TEST["sts-test.csv"]:::data
        TEST_DATA["test_data.py"]:::data
    end

    %% Preprocessing Layer
    subgraph "Preprocessing"
        direction TB
        PRE["bert_preprocessing.py"]:::internal
    end

    %% Model Inference
    subgraph "Model Inference"
        direction TB
        SIM["similarity.py"]:::internal
        LEX["lexical_similarity_metrics.py"]:::api
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        UTIL["util.py"]:::internal
        TEST_UTIL["test_util.py"]:::internal
    end

    %% External Dependencies
    subgraph "External"
        direction TB
        HF["Huggingface Transformers"]:::external
        DEVICE["GPU/CPU"]:::external
        CACHE["Local Cache"]:::external
    end

    %% User to API
    U1 -->|calls| API2
    U1 -->|calls| API3
    U2 -->|calls| API1
    U2 -->|calls| API3

    %% API to Data and Processing
    API1 -->|load data| DL
    API2 -->|load data| DL
    API3 -->|compute metrics| LEX

    DL --> STS_TRAIN
    DL --> STS_DEV
    DL --> STS_TEST
    DL --> TEST_DATA

    %% Data to Preprocessing
    DL -->|raw text| PRE
    PRE -->|token IDs| SIM

    %% Lexical path
    LEX -->|score| API3

    %% BERT Inference path
    SIM -->|forward pass| HF
    SIM -->|executes on| DEVICE
    HF -->|cache lookup| CACHE

    SIM -->|score| API1
    SIM -->|score| API2

    %% Return to User
    API1 -->|returns score| U2
    API2 -->|returns score| U1

    %% Click Events
    click U1 "https://github.com/andriymulyar/semantic-text-similarity/blob/master/examples/med_sts_clinical.py"
    click U2 "https://github.com/andriymulyar/semantic-text-similarity/blob/master/examples/sts_b_web.py"
    click API1 "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/bert/web_similarity.py"
    click API2 "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/bert/clinical_similarity.py"
    click API3 "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/string_similarity/lexical_similarity_metrics.py"
    click DL "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/data/data.py"
    click STS_TRAIN "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/data/sts_b/sts-train.csv"
    click STS_DEV "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/data/sts_b/sts-dev.csv"
    click STS_TEST "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/data/sts_b/sts-test.csv"
    click TEST_DATA "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/data/test_data.py"
    click PRE "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/bert/bert_preprocessing.py"
    click SIM "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/bert/similarity.py"
    click UTIL "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/util.py"
    click TEST_UTIL "https://github.com/andriymulyar/semantic-text-similarity/blob/master/semantic_text_similarity/models/test_util.py"
    click setup "https://github.com/andriymulyar/semantic-text-similarity/blob/master/setup.py"
    click readme "https://github.com/andriymulyar/semantic-text-similarity/blob/master/README.md"

    %% Styles
    classDef user fill:#eef,stroke:#88a;
    classDef api fill:#cfc,stroke:#2a2;
    classDef internal fill:#ccf,stroke:#448;
    classDef data fill:#ccf,stroke:#448;
    classDef external fill:#fec,stroke:#e52;
```
