How uditrpanchal/trm-sudoku-neural-solver works
Project Type and Purpose
• This is a full-stack, end-to-end Sudoku solving toolkit.
• Backend: Python-based ML pipeline (dataset generator, tiny MLP-Mixer model, classical backtracking solver) exposed via CLI and FastAPI.
• Frontend: Vite + React + Tailwind dashboard for interactive experimentation, metrics, and visualization.
High-Level File Structure Analysis
• Top-level files:
• solve_sudoku.py – CLI entry point
• web_backend.py – FastAPI app exposing /api endpoints
• sudoku_pipeline.py – Orchestrator for dataset → model training/inference → solver refinement → metrics/logging
• tiny_recursive_model.py – PyTorch MLPMixer implementation + training harness
• sudoku_utils.py – Puzzle generation + classical backtracking solver + validation helpers
• sudoku_dataset.py – torch.utils.data.Dataset wrapper around on-the-fly puzzle generation
• train_models.py – Batch training script for research/benchmarks
• Various analysis scripts (inference.py, investigate_accuracy.py, debug_difficulty.py, etc.)
• frontend/ – React dashboard with API client, UI components, theme provider, metrics/logs panels
• Dockerfile – Container image spec for serving FastAPI + CPU Torch
Key Insights from README
• ML backbone: TinyRecursiveModel (1D MLPMixer)
• Refinement: Deterministic backtracking solver
• Exposed interfaces:
• CLI runner (solve_sudoku.py)
• FastAPI REST (web_backend.py + uvicorn)
• React Dashboard (frontend/)
• No persistent database; puzzles generated on demand.
Components
a. Client-side
• CLI Client (solve_sudoku.py)
• React Web UI (browser + Vite dev server / production build)
b. API Layer
• FastAPI App (web_backend.py)
• UVicorn Server
c. Orchestration & Business Logic
• Sudoku Pipeline (sudoku_pipeline.py)
• Training Scripts (train_models.py)
• Analysis Scripts (inference.py, investigate_accuracy.py, etc.)
d. ML Component
• TinyRecursiveModel (tiny_recursive_model.py)
• Dataset Generator (sudoku_dataset.py + sudoku_utils.py)
e. Classical Solver
• Backtracking Algorithm (sudoku_utils.py)
f. Auxiliary
• Logging & Metrics (inside pipeline; streamed via API)
• Docker Container (Dockerfile)
• Asset Store (assets/ for README screenshot)
g. Development & Build
• npm / Vite (frontend)
• pip / requirements.txt (backend)
Relationships and Data Flows
• CLI Client and Web UI → send run requests → FastAPI App
• FastAPI App → invokes Sudoku Pipeline
• Pipeline →
1. Generates puzzle via sudoku_dataset + sudoku_utils
2. Runs TinyRecursiveModel inference/training
3. Applies backtracking solver for refinement
4. Collects metrics & logs
• Pipeline returns results to FastAPI → API response → CLI prints or Web UI renders
• Web UI polls API endpoints (/api/health, /api/difficulties, /api/generate_puzzle, /api/run) via HTTP
• Development pipelines: train_models.py & analysis scripts call pipeline directly for research (no HTTP)
Architectural Patterns & Principles
• Layered architecture: Presentation (CLI, UI), API/controller (FastAPI), Domain logic (pipeline), Data/algorithmic modules (model, solver).
• Single-repository monorepo with clear separation of concerns.
• Reusable pipeline core for both CLI and API.
• Stateless service—no persistent storage; leverages on-the-fly generation.
Technology Stack
• Backend: Python 3.10+, FastAPI, Uvicorn, PyTorch (CPU/Torch GPU), torch.utils.data
• Frontend: Node.js 18+, Vite, React, TypeScript, Tailwind CSS, shadcn-style primitives, Radix UI, Sonner toasts
• Containerization: Docker
• Testing: pytest (test_*.py)