Upload folder using huggingface_hub

Dockerfile

@@ -1,7 +1,14 @@
+# Python 3.10 (slim) as base
 FROM python:3.10-slim
+
+# THhis is the working directory of the container
 WORKDIR /code
+
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the entire application code into the container
 COPY . .
-# We run from /code so that 'frontend/' and 'models/' are visible to app.py
+
+# Run the FastAPI application using uvicorn on all interfaces at port 7860
 CMD ["uvicorn", "backend.app:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -1,3 +1,5 @@
+# MIT License
+
 © 2026 intelligent-username
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
@@ -5,3 +7,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

README.md

@@ -6,19 +6,24 @@ colorTo: gray
 sdk: docker
 app_port: 7860
 ---
+
 # Optical Character Recognition
 
 ![Demonstration](https://varak.dev/host/EMNIST-OCR-DEMO.webp)
 
 Use the tool live [here](https://ocr.varak.dev).
 
-This is an optical character recognition (OCR) tool that extracts characters from drawings.  Using basic JS/HTML, we create a canvas to draw on, convert the drawing toa usable 28x28 pixel format, and send to the backend for prediction. In the backend, we use FastAPI to handle requests, with the only routes being `/` for the home page and `/predict` for predictions. The prediction route uses a pre-trained CNN model that is able to recognize all English characters and digits. For more details on the architecture, the dataset, and training process, check out [this writeup](https://github.com/intelligent-username/CNN/tree/main/char), which presents the simpler of two models trained for my writeup on CNNs (this one). For a better understanding of CNNs in general, check out this [broader writeup](https://github.com/intelligent-username/CNN).
+This is an optical character recognition (OCR) tool that extracts characters from drawings. It's made with FastAPI for the backend, vanilla JS/HTML for the frontend, and the model was trained using PyTorch.
+
+The project creates a canvas to draw on, converts the drawing to a usable 28x28 pixel format, and sends it to the backend for prediction.
+
+The only two routes for the backend are `/` for the home page and `/predict` for prediction API. The prediction route recognizes all English characters and digits. For more details on the architecture, the dataset, and training process, check out [this writeup](https://github.com/intelligent-username/CNN/tree/main/char), which presents the simpler of two models trained for my [writeup on CNNs](https://github.com/intelligent-username/CNN).
 
 ## Usage
 
 Once again, the tool is hosted [here](https://ocr.varak.dev) for easy access. 
 
-Draw the character you want to recognize on the left canvas. The right canvas will display the top-k predictions, where k can be adjusted using the slider below it. The slider is capped at 15 since, after 15, all of the predictions are basically at 0% probability.
+Draw the character you want to recognize on the left canvas. The right canvas will display the top-k predictions, where k can be adjusted using the slider below it. The slider is capped at 15 since, after 15, all of the predictions are basically guaranteed to be at 0% probability.
 
 To run this project locally, take the following steps:
 
@@ -35,8 +40,8 @@ cd OCR
 
 ```bash
 python -m venv OCR-env
-OCR-env\Scripts\activate  # On Windows
-source OCR-env/bin/activate  # On macOS/Linux
+OCR-env\Scripts\activate        # On Windows
+source OCR-env/bin/activate     # On mac/Linux
 pip install -r requirements.txt
 ```
 

backend/__init__.py

@@ -1 +1 @@
-# Just for Docker
+# Modularize

backend/app.py

@@ -1,6 +1,7 @@
 import torch as t
 import asyncio
 import os
+import shutil
 
 from backend.utils import predict_image
 from backend.model import EMNIST_VGG
@@ -54,8 +55,6 @@ if not os.path.exists(MODEL_PATH):
     # This downloads the file and returns the local path
     downloaded_path = hf_hub_download(repo_id=REPO_ID, filename=FILENAME)
     
-    # Optional: Move it to your backend folder so your existing load logic works
-    import shutil
     shutil.copy(downloaded_path, MODEL_PATH)
     print(f"Weights secured at {MODEL_PATH}")
 

backend/model.py

@@ -1,12 +1,13 @@
 """
 VGG-style CNN for EMNIST character classification.
-See the README for a better description.
+See the README for a more detailed description.
 """
 
 # The .pth file (weights) for this model will be downloaded from HuggingFace by app.py
 # It's hosted at https://huggingface.co/compendious/EMNIST-OCR-WEIGHTS/
 # The file is EMNIST_CNN.pth
-# Go here to download directly: https://huggingface.co/compendious/EMNIST-OCR-WEIGHTS/resolve/main/EMNIST_CNN.pth?download=true
+# Go here to download directly: 
+#               https://huggingface.co/compendious/EMNIST-OCR-WEIGHTS/resolve/main/EMNIST_CNN.pth?download=true
 
 import torch
 import torch.nn as nn

backend/utils.py

@@ -4,6 +4,19 @@ import numpy as np
 MAX_CLASSES = 15
 
 def predict_image(image: list[float], model, device, top_k: int = 10) -> dict:
+    """
+    Docstring for predict_image
+    
+    :param image: Description
+    :type image: list[float]
+    :param model: Description
+    :param device: Description
+    :param top_k: Description
+    :type top_k: int
+    :return: Description
+    :rtype: dict
+    """
+
     # RESHAPE
     # Input comes in as flat 784 list -> (1 batch, 1 channel, 28 height, 28 width)
     x = t.tensor(image, dtype=t.float32).view(1, 1, 28, 28)

frontend/helpers/Sanitizer.js

@@ -1,3 +1,8 @@
+// Take Canvas input (left)
+// Convert 420x420 to 28x28
+// Then convert to Binary
+// So it can be sent to the API
+
 const blockSize = 15; // 420 / 28 = 15
 
 // Input Processor

frontend/helpers/barGraphs.js

@@ -1,3 +1,6 @@
+// Take response from API
+// Draw final output
+
 function drawPredictionGraph(canvas, predictions) {
     const ctx = canvas.getContext("2d");
     const w = canvas.width;

frontend/helpers/footer.js

@@ -1,3 +1,5 @@
+// Just the footer w/ basic info
+
 function initFooter() {
     const footer = document.createElement('footer');
     footer.className = 'footer';

frontend/helpers/kSlider.js

@@ -1,7 +1,10 @@
+// top-k bar chart display slider
+
 const slider = document.getElementById("k-slider");
 const output = document.getElementById("k-value");
 
 // Initialize w/ default
+// 10 rn
 output.textContent = slider.value;
 
 // Update number instantly on drag

frontend/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
     <meta charset="UTF-8" />
-    <title>EMNIST OCR Canvas</title>
+    <title>EMNIST OCR Canvases</title>
     <link rel="stylesheet" href="/static/style.css" />
 </head>
 <body>

frontend/main.js

@@ -1,4 +1,4 @@
-// main.js is just for putting everything together quickly and simply. Don't grow into a monolith or complicate the project.
+
 
 const canvas = document.getElementById("draw-canvas");
 // Use willReadFrequently to optimize repeated getImageData readbacks

frontend/style.css

@@ -1,3 +1,5 @@
+/* Each style is basically just for 1 element */
+
 body {
     font-family: 'Consolas', 'Courier New', monospace;
     margin: 0;

requirements.txt

@@ -1,9 +1,15 @@
-fastapi
-uvicorn
-aiofiles
-torch --index-url https://download.pytorch.org/whl/cpu
-torchvision --index-url https://download.pytorch.org/whl/cpu
-numpy
-pydantic
+--extra-index-url https://download.pytorch.org/whl/cpu
 
-huggingface-hub
+# ML
+torch==2.5.1
+torchvision==0.20.1
+numpy==1.26.4
+
+# Frameworx
+fastapi==0.115.6
+pydantic==2.10.3
+uvicorn==0.34.0
+aiofiles==24.1.0
+
+# Utilz
+huggingface-hub==0.27.0