# jellyfish042/sudoku-rwkv architecture

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

- Interactive diagram: https://gitdiagram.com/jellyfish042/sudoku-rwkv
- Repository: https://github.com/jellyfish042/sudoku-rwkv

## Overview

##### Main components
- Data Generation: The file generate_sudoku_data.py is used for creating Sudoku training samples. The training data is stored in sudoku_data.jsonl and the corresponding sudoku_vocab.txt file defines the vocabulary.
- Model Definition and Training Enhancements: The model.py file (with noted modifications on line 372) defines the specialized RWKV model, including its architecture and enhancements. This component encapsulates the core logic of the network (8 layers, 320 dimensions) and the improvements made for better performance.
- Inference Engine: The inference process is handled by rwkv_model.py and minimum_inference.py. References to lines 852 and 893-896 in rwkv_model.py indicate that these files contain adjustments for running predictions with the trained model.
- Utilities & Formatting: The utility functions in utils.py and formatter.py support the core processes, ensuring proper data handling, formatting, and possibly error checking.

##### Understanding the relationships and interactions
- Training Data Generation flows into the training process – generate_sudoku_data.py produces the data, while sudoku_data.jsonl and sudoku_vocab.txt are then utilized during the model training (which actually occurred using external RWKV-LM code).
- The Model component (model.py) represents the learned network, which is saved as sudoku_rwkv_20241120.pth. Inference scripts (rwkv_model.py and minimum_inference.py) load this model to perform Sudoku solving.
- The demo script (demo.py) integrates inputs from the user (possibly via tkinter) and triggers the inference process to solve puzzles.
- The utilities and formatting support modules ensure that data parsing, output formatting, and any ancillary processing are performed correctly.

##### Highlights of architectural patterns and design principles
- Modularity: Each Python script represents a specific functionality (data generation, model definition, inference, demo/UI, utilities). This separation of concerns aligns with modular design principles.
- Data Flow Separation: There is a clear separation from generated training data to model training (external) and then to model inference and demonstration.
- Custom Improvements: The notes indicate that modifications in model.py and rwkv_model.py provide performance enhancements, signaling targeted custom improvements to a foundational model.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Generation"
        DS1["generate_sudoku_data.py"]:::data
        DS2["sudoku_data.jsonl"]:::data
        DS3["sudoku_vocab.txt"]:::data
    end

    subgraph "Model Definition & Training"
        M1["model.py (modified@line372)"]:::compute
        M2["sudoku_rwkv_20241120.pth"]:::compute
    end

    subgraph "Inference Engine"
        I1["rwkv_model.py (modified@lines852,893-896)"]:::compute
        I2["minimum_inference.py"]:::compute
    end

    subgraph "Demo/UI"
        D1["demo.py (tkinter)"]:::ui
        D2["assets"]:::ui
    end

    subgraph "Utilities & Formatter"
        U1["utils.py"]:::utils
        U2["formatter.py"]:::utils
    end

    %% Connections showing data flow and dependencies
    DS1 -->|"generates-data"| M1
    DS2 ---|"training_data"| M1
    DS3 ---|"vocabulary"| M1

    M1 -->|"defines-model"| M2
    M2 -->|"loaded-by"| I1

    I1 -->|"inference-output"| D1

    U1 -->|"supports"| I1
    U1 -->|"supports"| D1
    U2 -->|"formats"| I1
    U2 -->|"formats"| D1

    %% Styling for a clear vertical layout (connections arranged top-down)
    %% Click Events
    click DS1 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/generate_sudoku_data.py"
    click DS2 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/sudoku_data.jsonl"
    click DS3 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/sudoku_vocab.txt"
    click M1 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/model.py"
    click M2 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/sudoku_rwkv_20241120.pth"
    click I1 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/rwkv_model.py"
    click I2 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/minimum_inference.py"
    click D1 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/demo.py"
    click D2 "https://github.com/jellyfish042/sudoku-rwkv/tree/main/assets/"
    click U1 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/utils.py"
    click U2 "https://github.com/jellyfish042/sudoku-rwkv/blob/main/formatter.py"

    %% Styles
    classDef data fill:#a8d0e6,stroke:#000,stroke-width:2px;
    classDef compute fill:#bdecb6,stroke:#000,stroke-width:2px;
    classDef ui fill:#fff2ab,stroke:#000,stroke-width:2px;
    classDef utils fill:#ffcccb,stroke:#000,stroke-width:2px;
```
