{"id":16778688,"url":"https://github.com/ritvik19/sudokunet","last_synced_at":"2025-08-31T05:37:39.469Z","repository":{"id":213119500,"uuid":"733075258","full_name":"Ritvik19/SudokuNet","owner":"Ritvik19","description":"Ai Sudoku Solver","archived":false,"fork":false,"pushed_at":"2024-04-10T12:11:32.000Z","size":54,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-16T19:48:28.527Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ritvik19.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-18T14:03:28.000Z","updated_at":"2024-09-26T02:26:30.000Z","dependencies_parsed_at":"2023-12-18T15:58:01.022Z","dependency_job_id":"66712e41-2860-49ae-a7d4-c923228f8c81","html_url":"https://github.com/Ritvik19/SudokuNet","commit_stats":null,"previous_names":["ritvik19/sudokunet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Ritvik19/SudokuNet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ritvik19%2FSudokuNet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ritvik19%2FSudokuNet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ritvik19%2FSudokuNet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ritvik19%2FSudokuNet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ritvik19","download_url":"https://codeload.github.com/Ritvik19/SudokuNet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ritvik19%2FSudokuNet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272942395,"owners_count":25019328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T07:28:27.250Z","updated_at":"2025-08-31T05:37:39.433Z","avatar_url":"https://github.com/Ritvik19.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SudokuNet\n\nAi Sudoku Solver\n\nThis repository contains scripts and resources for training Sudoku Net\n\n## Dataset\n\nThe model is trained on a dataset comprising 17 million Sudoku puzzles from various sources ([Dataset Card](https://huggingface.co/datasets/Ritvik19/Sudoku-Dataset)). The dataset includes puzzle configurations, solutions, difficulty levels, and sources.\n\n## Model\n\n### Model Architecture\n\nThe solver utilizes a Feed Forward Neural Network architecture. Details about the layers, units, and unique aspects of the architecture can be found in the [Model Card](https://huggingface.co/Ritvik19/SudokuNet).\n\n### Training\n\nThe training process involves using the Adam optimizer with a learning rate of 1e-3 and a batch size of 64K. Training and evaluation scripts are available in the `src` directory.\n\n### Performance Metrics\n\nThe model's performance is evaluated based on accuracy, indicating whether the model correctly solves Sudoku puzzles or not. Further insights on performance metrics are detailed in the [Model Card](https://huggingface.co/Ritvik19/SudokuNet).\n\n### Getting the Pretrained Models\n\nTo fetch pretrained models from the remote model repository\n\n```python\nfrom huggingface_hub import hf_hub_download\n\nmodel_file_path = hf_hub_download(\n    repo_id=\"Ritvik19/SudokuNet\",\n    filename=\"model_filename_here\",\n)\n```\n\n#### Pretrained Models\n\n| Model Filename         | Accuracy |\n| ---------------------- | -------: |\n| ffn__64x2.keras        |  0.92932 |\n| ffn__64x4.keras        |  0.92928 |\n| ffn__128x2.keras    👑 |  0.92968 |\n| ffn__128x4.keras       |  0.92892 |\n| cnn__64x2.keras        |  0.92796 |\n| cnn__64x4.keras     👑 |  0.93030 |\n| cnn__128x2.keras       |  0.92786 |\n| cnn__128x4.keras       |  0.92878 |\n\n## Usage\n\n### Interacting with the Model\n\nUsers can interact with the trained model through this [Space](https://huggingface.co/spaces/Ritvik19/SudokuNetDemo).\n\n## Getting Started\n\n### Installation\n\nTo install the required dependencies, run:\n\n```bash\npip install -r requirements.txt\n```\n\n### Model Definitions\n\nFollowing predefined models are available:\n\n1. **Feed Forward Neural Network (FFN):** Defined in `ffn.py`\n2. **Convolutional Neural Network (CNN):** Defined in `cnn.py`\n3. **Bidirectional Recurrent Neural Network (RNN):** Defined in `rnn.py`\n4. **Bidirectional Long Short-Term Memory (LSTM):** Defined in `lstm.py`\n5. **Bidirectional Gated Recurrent Unit (GRU):** Defined in `gru.py`\n\n### Custom Model Architecture\n\nIf you want to define a custom architecture, follow these steps:\n\n1. Inherit from the `SudokuNetTrainer` class.\n2. Override the `build_model` method to define your custom architecture.\n\nExample of custom model definition:\n\n```python\nfrom trainer import SudokuNetTrainer\n\nclass CustomSudokuNetTrainer(SudokuNetTrainer):\n    def build_model(self):\n        # Define your custom architecture here\n        # ...\n\n# Use the CustomSudokuNetTrainer in main.py\n```\n\n### Training the Model\n\nTo train the model, use the `main.py` script with the following options:\n\n```bash\nusage: main.py [-h] [--train TRAIN [TRAIN ...]] [--valid VALID [VALID ...]] [--model-load MODEL_LOAD] [--model-save MODEL_SAVE] [--model-type MODEL_TYPE]\n               [--num-delete NUM_DELETE] [--epochs EPOCHS] [--batch-size BATCH_SIZE] [--resume]\n\ntrain sudoku net\n\noptions:\n  -h, --help            show this help message and exit\n  --train TRAIN [TRAIN ...]\n                        the path of the dataset file\n  --valid VALID [VALID ...]\n                        the path of the dataset file\n  --model-load MODEL_LOAD\n                        the path of the model file to load\n  --model-save MODEL_SAVE\n                        the path of the model file to save\n  --model-type MODEL_TYPE\n                        the type of model to train\n  --num-delete NUM_DELETE\n                        the number of digits to delete\n  --epochs EPOCHS       the number of epochs to train\n  --batch-size BATCH_SIZE\n                        the batch size to train\n  --resume              resume training from the model file\n```\n\nAdjust the options according to your requirements. For example, to train the FFN model with a specific dataset, use:\n\n```bash\npython main.py --train path/to/train_data.parquet --valid path/to/valid_data.parquet --model-type ffn\n```\n\nFeel free to customize the training parameters as needed.\n\n### Inference\n\nPerforming inference with the trained model can be done using the `SudokuSolver` class:\n\n1. **Instantiate the SudokuSolver Class:**\n\n```python\nfrom infer import SudokuSolver\n\n# Provide the path to the trained model\nmodel_path = 'path/to/your/model_file'\n\n# Instantiate the SudokuSolver object\nsolver = SudokuSolver(model_path)\n```\n\n2. **Solve Sudoku Puzzles:**\n\n```python\n# Provide the puzzle as input to the solver object\npuzzle = [\n    [5, 3, 0, 0, 7, 0, 0, 0, 0],\n    [6, 0, 0, 1, 9, 5, 0, 0, 0],\n    [0, 9, 8, 0, 0, 0, 0, 6, 0],\n    [8, 0, 0, 0, 6, 0, 0, 0, 3],\n    [4, 0, 0, 8, 0, 3, 0, 0, 1],\n    [7, 0, 0, 0, 2, 0, 0, 0, 6],\n    [0, 6, 0, 0, 0, 0, 2, 8, 0],\n    [0, 0, 0, 4, 1, 9, 0, 0, 5],\n    [0, 0, 0, 0, 8, 0, 0, 7, 9]\n]\n\n# Call the solver object with the puzzle to get the solution\nsolution = solver(puzzle)\n```\n\nReplace `'path/to/your/model_file'` with the actual path to your trained model file. Input your Sudoku puzzle as a 9x9 matrix with 0s indicating empty cells. The solver object will return the solution for the provided puzzle.\n\n## Contribution\n\nContributions are welcome! If you want to contribute to this project, please follow the follwing guidelines:\n\n1. **Fork** the repository and create your branch from `main`.\n2. **Discuss** major changes or enhancements by opening an issue first.\n3. **Commit** changes with descriptive commit messages.\n4. **Testing** is appreciated; ensure your code is thoroughly tested.\n5. **Pull Requests** should be linked to an open issue and provide a clear explanation of changes.\n\n### Code Style\n\n- Follow consistent coding styles as present in the repository.\n- Comment your code where necessary to enhance readability.\n\n### Reporting Issues\n\n- If you encounter bugs or have suggestions, please open an issue.\n- Clearly explain the problem with steps to reproduce for bug reports.\n\n### Feature Requests\n\n- Open an issue to propose new features or improvements.\n- Describe the feature and its potential impact.\n\n### Pull Requests\n\n- Link your pull request to the related issue for easy tracking.\n- Provide a concise summary of changes in the PR description.\n\nYour contributions will be highly appreciated and acknowledged!\n\n## License\n\nThis project is licensed under Apache-2.0. Refer to `LICENSE` for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fritvik19%2Fsudokunet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fritvik19%2Fsudokunet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fritvik19%2Fsudokunet/lists"}