# conti748/wyze-rule-recommendation architecture

> Architecture diagram of the GitHub repository conti748/wyze-rule-recommendation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/conti748/wyze-rule-recommendation
- Repository: https://github.com/conti748/wyze-rule-recommendation

## Overview

##### Project type and purpose
- Type: A machine-learning pipeline (a full-stack ML application, focused on training and inference).
- Purpose: Given a user’s smart-home device graph, propose new automation rules by casting it as a graph link-prediction task using a GNN (PyTorch-Geometric).

##### File structure
- Top-level scripts: `train.py`, `test.py`, `test.py`, `test.py` handle end-to-end training and evaluation.
- Configuration: `cfg/` holds device/rule encodings and training hyperparameters (`training.yaml`).
- Data: `data/` (inputs), `models/` (checkpoints), `results/` (output artifacts).
- Core modules:
- `modules/data_pipeline/GraphDataset.py` and `RulesDataset.py` build per-user graph objects.
- `modules/utils/` holds sampling, decoding, general utilities.
- `modules/LinkPredictor.py` defines the GNN architecture.
- Requirements: `requirements.txt` declares dependencies (PyTorch, PyTorch-Geometric, HuggingFace Hub).

##### Extract additional insights from README
- External dependency: downloads the “wyzelabs/RuleRecommendation” dataset from HuggingFace Hub.
- Problem framing: each user’s devices = nodes, rules = directed, typed edges. Node features: one‐hot device type. Edge features: trigger/action states (45×47).
- Model: embeds states and node types → two SageConv layers → concatenated embeddings → classification head (sigmoid).
- Training: positive (leave-one-out) & negative sampling → BCE loss.
- Evaluation: compute MRR on public/private splits.

##### Main components and interactions
a. Data Ingestion & Configuration
- External Dataset (HuggingFace Hub)
- Local config files (`cfg/`)
→ feeds into

b. Data Pipeline
- GraphDataset: reads rules + device lists → builds PyG `Data` objects (nodes, edges, features)
- RulesDataset: helper for batching/testing
- Sampling Utils: positive/negative sampling modules
→ yields training/test batches

c. Model
- LinkPredictor (GNN):
- Embedding layers for trigger/action states
- Node feature concatenation (node type + aggregated edge embeddings)
- 2×SageConv layers
- Classification head → edge probability scores
→ outputs per‐pair link scores

d. Training & Evaluation
- `train.py`: loads config, instantiates datasets & model, runs training loop, logs loss/metrics, stores `best_model.ckpt` in `models/`
- `test.py`: loads checkpoint, loads dataset split (public/private), generates top-50 rule suggestions, computes MRR → stores in `results/`

e. Storage & Artifacts
- `models/`: serialized model checkpoints
- `results/`: evaluation outputs
- `docs/`: architecture slides & images

- Clear labels for each component and sub-component

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion & Configuration"
        HF["HuggingFace Hub"]:::external
        cfg["cfg/"]:::data
        training_yaml["training.yaml"]:::data
        device_enc["device_encoding.json"]:::data
        rule_enc["rule_encoding.json"]:::data
        data_raw["data/"]:::data
    end

    subgraph "Data Pipeline"
        GD["GraphDataset"]:::pipeline
        RD["RulesDataset"]:::pipeline
        SP["sampling.py"]:::pipeline
        DC["decode_results.py"]:::pipeline
        UT["utils.py"]:::pipeline
    end

    subgraph "Model"
        LP["LinkPredictor"]:::model
    end

    subgraph "Training & Evaluation"
        TR["train.py"]:::script
        TE["test.py"]:::script
    end

    subgraph "Storage & Artifacts"
        MD["models/"]:::storage
        RD2["results/"]:::storage
        DOC["docs/"]:::storage
    end

    HF -->|"dataset JSON"| GD
    cfg -->|"config files"| GD
    cfg -->|"config files"| TR
    data_raw -->|"raw data"| GD

    GD -->|"PyG Data objects"| RD
    GD -->|"PyG Data objects"| SP
    UT -->|"utilities"| GD
    UT -->|"utilities"| SP

    SP -->|"training batches"| TR
    TR -->|"training loop"| LP
    TR -->|"checkpoint"| MD

    TE -->|"inference"| LP
    TE -->|"MRR metrics"| RD2
    TE -->|"decode results"| DC
    UT -->|"utilities"| TE

    click cfg "https://github.com/conti748/wyze-rule-recommendation/tree/master/cfg/"
    click training_yaml "https://github.com/conti748/wyze-rule-recommendation/blob/master/cfg/training.yaml"
    click device_enc "https://github.com/conti748/wyze-rule-recommendation/blob/master/cfg/device_encoding.json"
    click rule_enc "https://github.com/conti748/wyze-rule-recommendation/blob/master/cfg/rule_encoding.json"
    click data_raw "https://github.com/conti748/wyze-rule-recommendation/tree/master/data/"
    click GD "https://github.com/conti748/wyze-rule-recommendation/blob/master/modules/data_pipeline/GraphDataset.py"
    click RD "https://github.com/conti748/wyze-rule-recommendation/blob/master/modules/data_pipeline/RulesDataset.py"
    click SP "https://github.com/conti748/wyze-rule-recommendation/blob/master/modules/utils/sampling.py"
    click DC "https://github.com/conti748/wyze-rule-recommendation/blob/master/modules/utils/decode_results.py"
    click UT "https://github.com/conti748/wyze-rule-recommendation/blob/master/modules/utils/utils.py"
    click LP "https://github.com/conti748/wyze-rule-recommendation/blob/master/modules/LinkPredictor.py"
    click TR "https://github.com/conti748/wyze-rule-recommendation/blob/master/train.py"
    click TE "https://github.com/conti748/wyze-rule-recommendation/blob/master/test.py"
    click MD "https://github.com/conti748/wyze-rule-recommendation/tree/master/models/"
    click RD2 "https://github.com/conti748/wyze-rule-recommendation/tree/master/results/"
    click DOC "https://github.com/conti748/wyze-rule-recommendation/tree/master/docs/"

    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef pipeline fill:#90EE90,stroke:#333,stroke-width:1px
    classDef model fill:#FFA500,stroke:#333,stroke-width:1px
    classDef script fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#87CEFA,stroke:#333,stroke-width:1px
```
