# lefteris12/multitask-schema-guided-dst architecture

> Architecture diagram of the GitHub repository lefteris12/multitask-schema-guided-dst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lefteris12/multitask-schema-guided-dst
- Repository: https://github.com/lefteris12/multitask-schema-guided-dst

## Overview

##### Project type and purpose
- This is an open-source Python toolkit implementing a multi-task BERT model for Schema-Guided Dialogue State Tracking (DST).
- It provides data-processing pipelines, PyTorch datasets, training/evaluation scripts, and a baseline BERT implementation under `mtsgdst/schema_guided_dst/baseline`.

##### File structure
- Top level:
– `download_data.sh` – helper to clone the SGD dataset.
– `mtsgdst/` – the main package.
– `train.py`, `dst.py` – CLI entrypoints for training and inference.
– `config.py` – global hyperparameter/config definitions.
- `mtsgdst/data/` – raw data ingestion, EDA, feature extraction, dialogue processing, input-sequence construction, and two dataset classes (`pytorch_dataset.py` for SGD and `sgd_dataset.py` for low-level.
- `mtsgdst/schema_guided_dst/` – implements the schema-guided logic. Within it:
– `baseline/bert/` – a self-contained BERT modeling, tokenization, optimization, data utilities, and train/predict script.
– multiwoz/ – schema conversion for the MultiWOZ dataset.
– metrics/ – code to compute DST metrics.
– evaluate.py – script to measure performance against references.

##### README
- Describes the three sub-tasks (intent prediction, requested‐slot prediction, slot filling) all handled by one BERT.
- Provides instructions for environment setup, dataset creation, training, checkpointing, and evaluation.

1. External Data Sources
– Schema-Guided Dialogue (SGD) dataset repo
– MultiWOZ schema files (optional)
2. Data Ingestion & Preprocessing
– download_data.sh
– `mtsgdst/data/*`: JSON readers, EDA, feature extraction, input sequence builder
3. Dataset Serialization
– `mtsgdst/data/pytorch_dataset.py` → pickle files per split (train/dev/test)
4. Model Module
– BERT encoder + three classification heads (intent, requested slots, span‐extraction) in `mtsgdst/models.py`
– Schema encoding logic in `mtsgdst/schema_guided_dst/schema.py`
5. Training Orchestrator
– `mtsgdst/train.py`: loads config, DataLoader, model, optimizer, checkpoint manager
6. Checkpoint Storage
– `checkpoints/latest.pt` and `best.pt`
7. Evaluation & Metrics
– `mtsgdst/dst.py` for inference on test set
– `mtsgdst/schema_guided_dst/metrics.py` for joint goal accuracy, slot‐fill F1, etc.
8. Baseline Submodule (optional)
– `mtsgdst/schema_guided_dst/baseline` – standalone BERT baseline for comparison

- External Data → Data Ingestion & Preprocessing
- Preprocessing → Dataset Serialization
- Serialized datasets → Training Orchestrator (via PyTorch DataLoaders)
- Training → Checkpoint Storage
- Checkpoint Storage → Evaluation & Metrics
- Baseline Submodule can feed into Evaluation & Metrics as a parallel branch.

c. Architectural Patterns & Principles
- Modular layering: Data layer, Model layer, Orchestration layer, Evaluation layer.
- Single-model multi-task learning pattern: one shared encoder + multiple heads.
- Schema-guided abstraction: loose coupling between dialogue history and service schema representations.
- CLI façade: train.py and dst.py decouple implementation from run commands.

d. Key Technologies & Frameworks
- Python 3.10, PyTorch (Dataset, DataLoader, nn.Module)
- transformers-style BERT tokenizer/model (custom in `baseline/bert`)
- Pickle for dataset caching
- Standard JSON for dialogues and schema

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    SGDRepo["SGD Dataset Repo"]:::external
    MultiWOZ["MultiWOZ Schema Files"]:::external

    %% Data & Preprocessing Layer
    subgraph "Data Layer"
        direction TB
        Download["download_data.sh"]:::data
        Config["config.py"]:::data

        subgraph "Preprocessing Modules"
            direction TB
            Dialogue["dialogue_processing.py"]:::data
            EDA["eda.py"]:::data
            Feature["feature_extraction.py"]:::data
            InputSeq["input_sequence.py"]:::data
        end

        subgraph "Dataset Serialization"
            direction TB
            PytorchDS(("pytorch_dataset.pkl")):::storage
            SGDDS(("sgd_dataset.pkl")):::storage
        end
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        MF["models.py"]:::model
        SchemaEnc["schema.py"]:::model
        subgraph "BERT Multi-task"
            direction TB
            BERT["BERT Encoder"]:::model
            Intent["Intent Head"]:::model
            ReqSlots["Requested-Slots Head"]:::model
            SlotSpan["Slot-Span Head"]:::model
        end
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        TrainCLI["train.py"]:::orches
        DSTCLI["dst.py"]:::orches
    end

    %% Storage for Checkpoints
    Checkpoints(("checkpoints/*.pt")):::storage

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        direction TB
        EvalScript["evaluate.py"]:::orches
        Metrics["metrics.py"]:::orches
    end

    %% Baseline Submodule
    subgraph "Baseline Submodule"
        direction TB
        BaseConfig["config.py"]:::external
        subgraph "BERT Baseline"
            direction TB
            Modeling["modeling.py"]:::external
            Tokenization["tokenization.py"]:::external
            Optimization["optimization.py"]:::external
        end
        subgraph "Prediction Utils"
            direction TB
            Pred1["pred_utils.py"]:::external
            Pred2["pred_utils_new.py"]:::external
        end
        SchemaExtr["extract_schema_embedding.py"]:::external
        TrainPred["train_and_predict.py"]:::external
    end

    %% Connections
    SGDRepo -->|provides JSON| Download
    MultiWOZ -->|provides schema| SchemaEnc

    Download --> Dialogue
    Dialogue --> EDA
    EDA --> Feature
    Feature --> InputSeq

    InputSeq --> PytorchDS
    InputSeq --> SGDDS

    PytorchDS --> TrainCLI
    SGDDS --> TrainCLI

    Config --> TrainCLI
    TrainCLI --> BERT
    BERT --> Intent
    BERT --> ReqSlots
    BERT --> SlotSpan
    BERT -->|uses| SchemaEnc

    TrainCLI --> Checkpoints
    Checkpoints --> EvalScript
    EvalScript --> Metrics

    BaseConfig --> Modeling
    Modeling --> Tokenization
    Modeling --> Optimization
    Optimization --> Pred1
    Optimization --> Pred2
    Pred1 --> SchemaExtr
    Pred2 --> SchemaExtr
    SchemaExtr --> TrainPred
    TrainPred --> Metrics

    %% Click Events
    click Download "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/download_data.sh"
    click Config "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/config.py"
    click Dialogue "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/data/dialogue_processing.py"
    click EDA "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/data/eda.py"
    click Feature "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/data/feature_extraction.py"
    click InputSeq "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/data/input_sequence.py"
    click PytorchDS "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/data/pytorch_dataset.py"
    click SGDDS "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/data/sgd_dataset.py"
    click MF "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/models.py"
    click SchemaEnc "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/schema.py"
    click TrainCLI "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/train.py"
    click DSTCLI "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/dst.py"
    click EvalScript "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/evaluate.py"
    click Metrics "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/metrics.py"
    click BaseConfig "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/config.py"
    click Modeling "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/bert/modeling.py"
    click Tokenization "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/bert/tokenization.py"
    click Optimization "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/bert/optimization.py"
    click Pred1 "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/pred_utils.py"
    click Pred2 "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/pred_utils_new.py"
    click SchemaExtr "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/extract_schema_embedding.py"
    click TrainPred "https://github.com/lefteris12/multitask-schema-guided-dst/blob/main/mtsgdst/schema_guided_dst/baseline/train_and_predict.py"

    %% Styles
    classDef data fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef model fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef orches fill:#f9cb9c,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef storage fill:#adbac7,stroke:#333,stroke-width:1px
```
